@spec ask(name(), String.t(), timeout()) ::
  {:ok, GenAgent.Response.t()} | {:error, term()}

Send a synchronous prompt to an agent.

Blocks until the turn completes and returns {:ok, response} or {:error, reason}. If the agent is currently processing another prompt, the caller is queued transparently and unblocks when its queued turn finishes.

If admission to the pending prompt queue fails, returns {:error, {:overloaded, info}} immediately; no turn is accepted. info includes the queue, count or byte limit reached, current count and bytes, incoming bytes, and configured maxima.

The default timeout is :infinity. The agent's own watchdog is the primary timeout mechanism -- callers generally should not need to set their own. Supplying a shorter timeout here will raise on expiry without affecting the agent.

@spec child_spec(module(), keyword()) :: Supervisor.child_spec()

Build a temporary agent child spec for a caller-owned supervisor.

Requires :name, :backend, and :task_supervisor. The selected Task.Supervisor must already be running; prompt tasks never fall back to GenAgent.TaskSupervisor. Other options have the same meaning as in start_agent/2.

Start the spec with DynamicSupervisor.start_child/2. The agent is registered in GenAgent.Registry, so the regular name-based APIs work. Names must be unique across both caller-owned and global agents. Use stop/2 with the owning supervisor to stop an individual agent.

Put the task supervisor before the agent supervisor in the caller's supervision tree so agents shut down before their prompt-task supervisor. Use :rest_for_one if loss of the task supervisor should also stop the agents. See the README for an example.

@spec interrupt(name()) :: :ok

Interrupt an in-flight turn.

Kills the prompt task and delivers {:error, :interrupted} to the waiting caller (if any). No-op if the agent is idle.

Asynchronous. Returns :ok immediately.

@spec interrupt_request(name(), request_ref(), timeout()) ::
  {:ok, :accepted} | {:error, :not_current | :idle}

Interrupt the active turn only if its request reference matches ref.

Returns {:ok, :accepted} when the agent has cancelled that turn, {:error, :not_current} when another turn is active, or {:error, :idle} when no turn is active. A queued request is not interruptible through this API. Unlike interrupt/1, this operation is acknowledged by the agent and cannot cancel a successor turn after the observed request finishes. It is also safe against a replacement agent registered under the same name, because request references are unique.

The acknowledgement describes the agent's decision and BEAM task cancellation. It does not establish provider or OS process settlement. The default call timeout is :infinity.

@spec notify(name(), term()) :: :ok

Push an external event into the agent.

The event is delivered to handle_event/2. If the callback returns {:prompt, text, state} the prompt is dispatched (or queued, if the agent is busy).

Asynchronous. Returns :ok immediately, including when the agent later rejects the event because its pending queue is full. Rejections emit [:gen_agent, :input, :rejected] telemetry. Use notify_ack/3 when the sender needs an in-memory admission result.

@spec notify_ack(name(), term(), timeout()) :: :ok | {:error, term()}

Send an event and wait for the agent to acknowledge admission.

Returns :ok when the event was handled immediately or retained for delivery after the current turn. Returns {:error, {:overloaded, info}} when the pending notification queue cannot hold it, or an event handled while halted generates a prompt that cannot be queued. This acknowledges in-memory handling or retention, not durable delivery or a guarantee that a callback-generated prompt will run. A deferred callback-generated prompt can be rejected later if the prompt queue is full; the agent's handle_error/3 receives that overload. The legacy notify/2 remains a best-effort asynchronous cast and always returns :ok.

@spec poll(name(), request_ref(), timeout()) ::
  {:ok, :pending} | {:ok, :completed, GenAgent.Response.t()} | {:error, term()}

Check the status of a previously-issued tell/2 request.

Returns:

• {:ok, :pending} if the request is queued or in-flight.
• {:ok, :completed, response} if the turn finished successfully.
• {:error, reason} if the turn failed.
• {:error, :not_found} if the ref is unknown (never issued, or pruned from the bounded result cache).

Only refs returned from tell/2 are pollable. Refs from ask/2 are internal and reply directly to the caller.

@spec resume(name()) :: :ok

Resume a halted agent.

Clears the halted flag and re-drains the mailbox. No-op if the agent is not halted.

Asynchronous. Returns :ok immediately.

@spec runtime_snapshot(name(), timeout()) :: runtime_snapshot()

Read a bounded, metadata-only runtime snapshot of an agent.

pending_prompts counts the prompt mailbox; pending_notifications counts notifications buffered during a turn; self_chain_pending reports a separately held callback-generated follow-up prompt. current_request is nil when idle and otherwise contains the volatile request ref, its origin (:event and :self_chain are callback-origin turns), elapsed monotonic milliseconds since dispatch, and the configured watchdog duration. It excludes prompts, caller identities, callback state, backend sessions, events, and queued payloads. Elapsed time is an observation, not an exact countdown to the watchdog firing.

The snapshot is a point-in-time view of this BEAM coordinator, not durable application state, admission authority, or proof that external provider work has settled. The default call timeout is :infinity.

@spec start_agent(module(), keyword()) :: DynamicSupervisor.on_start_child()

Start an agent under the GenAgent supervision tree.

module is the implementation module (the one that use GenAgent). opts must include:

• :name -- the name the agent will register under in GenAgent.Registry.
• :backend -- the backend module implementing GenAgent.Backend.

Event evidence is bounded by :max_events_per_turn (default 1_000) and :max_event_bytes_per_turn (default 1_048_576), measured as the sum of :erlang.external_size/1 for each retained GenAgent.Event. Both limits must be positive integers. Reaching either limit before a terminal event fits fails the turn with {:event_capture_overflow, diagnostics}. No incomplete success response is returned. Accepted stream callbacks keep their state; the rejected event is not delivered to handle_stream_event/2.

Pending prompt and deferred notification queues have independent count and payload-byte limits: :max_pending_prompts and :max_pending_notifications (both default 1_000), and :max_pending_prompt_bytes and :max_pending_notification_bytes (both default 1_048_576). Limits are non-negative integers; zero disables that pending queue. Bytes are the sum of :erlang.external_size/1 of each queued prompt or notification payload, not the entire process memory. The active prompt and notifications handled immediately while idle are not pending. Self-chaining has one reserved slot outside the prompt count limit, but its payload must fit :max_pending_prompt_bytes.

Any other option is forwarded to init_agent/1. GenAgent-level knobs (like :watchdog_ms) are recognized and stripped before forwarding.

The child uses restart: :temporary. If it exits, call start_agent/2 explicitly to create another agent; its previous state is not restored.

@spec status(name(), timeout()) :: %{
  state: :idle | :processing,
  name: term(),
  queued: non_neg_integer(),
  current_request: request_ref() | nil,
  halted: boolean(),
  agent_state: term()
}

Read an agent's current status.

This compatibility API includes the full callback-maintained agent_state. While a turn is processing, that value is the server's latest retained state, not a live read of state inside the prompt task. Use runtime_snapshot/2 for a bounded metadata-only view.

@spec stop(name(), GenServer.server()) :: :ok | {:error, :not_found}

Stop an agent.

Terminates the agent process cleanly via its owning DynamicSupervisor. Pass the supervisor as the second argument for an agent started with child_spec/2; the default is GenAgent.AgentSupervisor. Returns :ok or {:error, :not_found}.

@spec tell(name(), String.t(), timeout()) :: {:ok, request_ref()} | {:error, term()}

Send an asynchronous prompt to an agent.

Returns {:ok, ref} immediately. Use poll/2 to check on the result. The same queueing semantics as ask/2 apply. When a pending queue limit is reached, returns {:error, {:overloaded, info}} without an accepted ref.

@spec tell_with_completion(name(), String.t(), pid(), timeout()) ::
  {:ok, request_ref()} | {:error, term()}

Submit an asynchronous prompt and opt into one completion message.

recipient is a pid (defaults to the calling process). On an accepted request this returns {:ok, ref} and sends the recipient {:gen_agent, :completion, name, ref, {:ok, response}} or {:gen_agent, :completion, name, ref, {:error, reason}} when the logical request finishes. The recipient is registered within the same agent call that accepts the request, so even an immediate pre_turn/2 skip or fast backend response can be delivered before this function returns. Match on the returned ref to correlate the message.

Admission failure returns {:error, {:overloaded, info}} with no ref or completion message. Accepted queued requests deliver after their turn completes; pre_turn/2 skip, halt and invalid results deliver their corresponding error without starting a turn. Successful and failed turns deliver after their decision and post_turn/3 callbacks. An interrupt, watchdog timeout or backend failure delivers an error. A crashing handle_response/3 callback stops the agent before completion; monitor the agent when its death matters to the caller.

Delivery is a single BEAM message sent at most once per accepted request. It is independent of the bounded poll/3 result cache. A dead recipient does not receive the message, and abrupt agent death can leave accepted requests without a completion message; a monitor reports that uncertainty. This does not prove that an external provider process has settled. The request ref remains suitable for interrupt_request/3, and a new agent under the same name never reuses it.

@spec whereis(name()) :: pid() | nil

Look up the pid of a registered agent, or nil if not found.