# `WardrikCore.Retry`

Retries model calls and tool calls that a retry may fix.

    WardrikCore.start_agent(
      agent_id: "triage",
      model: "anthropic:claude-haiku-4-5",
      retries: [attempts: 3, max_wait: :timer.seconds(10), on_exhausted: :fail]
    )

## Options

  * `:attempts` - retries after the first try. `6` by default.
  * `:max_wait` - the longest wait between tries, in milliseconds. Waits double from 1 second.
    `60_000` by default.
  * `:on_exhausted` - when a model call runs out of retries, `:ask` a person
    (see `WardrikCore.Retry.Exhausted`) or `:fail` the turn. `:ask` by default.

## What's retried

  * A model call that raised, such as on a timeout, a rate limit or a 5xx. Not a 4xx other than
    408, 425 and 429.
  * A tool call that raised, crashed or timed out, if its tool is `idempotent` or `read_only`.

A tool should return `{:error, reason}` when a retry won't help, and raise when it might.

# `t`

```elixir
@type t() :: keyword()
```

An agent's `:retries`. See the options above.

# `attempts`

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

Returns the number of retries after the first try.

# `on_exhausted`

```elixir
@spec on_exhausted(t()) :: :ask | :fail
```

Returns what a model call does once retries run out: `:ask` or `:fail`.

# `run`

```elixir
@spec run(t(), (-> answer),
  transient: (answer -> term() | nil),
  announce: (map() -> any())
) ::
  {:ok, answer} | {:spent, answer, pos_integer()}
when answer: term()
```

Runs `fun`, retrying while `:transient` returns a reason for its answer.

    WardrikCore.Retry.run([attempts: 3], fn -> fetch(url) end,
      transient: &transient/1,
      announce: &IO.inspect(&1, label: "retrying")
    )

`:transient` returns `nil` to stop. `:announce` is called before each wait. Returns
`{:ok, answer}`, or `{:spent, answer, tries}`.

# `transient?`

```elixir
@spec transient?(term()) :: boolean()
```

Returns whether a model call that failed with `reason` may succeed on retry.

---

*Consult [api-reference.md](api-reference.md) for complete listing*