ALLM.Error.SessionError exception (allm v0.4.1)

Session-state error. Returned (or raised) by ALLM.Session operations.

Layer A — serializable (no PIDs, refs, funs, or raw API keys). Every Layer-D public function can return {:error, %ALLM.Error.SessionError{}} uniformly.

Reasons

Reason	Fires when	Caller recovery
`:session_in_error_state`	Caller invokes a Layer-D operation on a `%Session{status: :error}`.	Construct a fresh session; do not retry.
`:invalid_status_for_operation`	Reserved for future use.	n/a
`:no_pending_tool_call`	Reserved for future use; the Layer-D status guard catches this case via `ArgumentError`.	n/a
`:unknown_tool_call_id`	`submit_tool_result/3` or `submit_tool_results/2` received a `tool_call_id` that does not match any pending `%ToolCall{}` on the session. Data validation, NOT a programmer-flow error.	Read `metadata.tool_call_id`; verify the caller is submitting against the right pending call.

Summary

Types

reason()

Closed set of session-level error reasons.

t()

Functions

new(reason, opts \\ [])

Build a %SessionError{} from a reason atom and optional keyword fields.

Types

reason()

@type reason() ::
  :session_in_error_state
  | :invalid_status_for_operation
  | :no_pending_tool_call
  | :unknown_tool_call_id

Closed set of session-level error reasons.

t()

@type t() :: %ALLM.Error.SessionError{
  __exception__: true,
  cause: term() | nil,
  message: String.t(),
  metadata: map(),
  provider: nil,
  reason: reason()
}

Functions

new(reason, opts \\ [])

@spec new(
  reason(),
  keyword()
) :: t()

Build a %SessionError{} from a reason atom and optional keyword fields.

opts may include :message, :cause, and :metadata. :provider is always nil for session errors (session is a Layer D concept; no provider context is meaningful). When :message is omitted, it defaults to "session error: #{reason}".

Raises ArgumentError if reason is not one of the atoms in the closed reason/0 enum.

Examples

iex> err = ALLM.Error.SessionError.new(:session_in_error_state)
iex> err.reason
:session_in_error_state
iex> Exception.message(err)
"session error: session_in_error_state"

iex> err = ALLM.Error.SessionError.new(:unknown_tool_call_id, metadata: %{tool_call_id: "c0"})
iex> err.metadata
%{tool_call_id: "c0"}