ALLM.Error.ToolError exception (allm v0.3.0)

Errors from tool handler execution.

Layer A — serializable. Note that :cause may carry a raised Exception struct, the exit reason, or an invalid term the handler returned. Callers should treat :cause as opaque and rely on :reason for programmatic dispatch.

Note: the spec §20 atom :tool_not_found is represented here as :not_found because the module name already carries the "tool" context.

See Phase 1 design §Sub-phase 1.1 for the closed reason enum.

Summary

Types

reason()

Closed set of tool-execution error reasons (spec §20).

t()

Functions

new(reason, opts \\ [])

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

Types

reason()

@type reason() ::
  :handler_raised
  | :handler_exit
  | :timeout
  | :invalid_return
  | :not_found
  | :encoding_failed

Closed set of tool-execution error reasons (spec §20).

t()

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

Functions

new(reason, opts \\ [])

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

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

opts may include :message, :tool_name, :tool_call_id, :cause, and :metadata. When :message is omitted, the default is "tool error: #{reason}" — with a tool-name suffix "tool error (#{tool_name}): #{reason}" when :tool_name is set.

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

Examples

iex> err = ALLM.Error.ToolError.new(:handler_raised)
iex> err.reason
:handler_raised
iex> Exception.message(err)
"tool error: handler_raised"

iex> err = ALLM.Error.ToolError.new(:timeout, tool_name: "search_web", tool_call_id: "call_1")
iex> err.tool_call_id
"call_1"
iex> Exception.message(err)
"tool error (search_web): timeout"