`model_mismatch` naming both, rather than silently answered by the grant's.

- Every successful proxy response attributes the effective model — the

  `x-openagents-model` header and each SSE chunk's `model` field — so a

  client renders what answered rather than what it assumed. A named model is

  never substituted: because a mismatch is refused, a caller that named one

  gets that one or an error.

  client renders what answered rather than what it assumed. Nothing in this

  application substitutes a named model: a mismatch is refused, so a caller

  that named one gets that one or an error.

- Amended 2026-08-25 (#250): one lane can be substituted for *by its provider*,

  and the response says so rather than the host pretending otherwise. Where

  `config :openagents, :vercel_gateway_fallback_models` is set, Vercel answers

  a failed primary with another model and returns 200. The proxy reads the

  serving model back off the response and attributes that, so the header and

  the chunks name what actually ran. Where such a lane discloses no model, the

  attribution is the word `unresolved` — not the requested model, which the

  deployment cannot claim served. An adapter says whether it can be

  substituted for (`OpenAgents.Providers.Provider.substitutable?/0`, false

  where it is not exported), so silence from a lane that cannot substitute

  still means the model that was asked for.

- Amended 2026-08-25 (#199): where **nothing named a model** — neither the

  mint nor the call — the server selects, preferring a configured lane that is

  not `degraded` in catalog order and falling back to the catalog default when

Evidence: `OpenAgents.Inference.Models`, `OpenAgentsWeb.ModelCatalogController`,

`OpenAgentsWeb.InferenceProxyController`, `OpenAgentsWeb.ThreadController`,

`OpenAgents.Inference.ModelsTest`, `OpenAgentsWeb.ModelCatalogControllerTest`,

`OpenAgentsWeb.InferenceProxyControllerTest`, and

`OpenAgentsWeb.InferenceProxyControllerTest`,

`OpenAgentsWeb.InferenceProxyFallbackTest`, and

`OpenAgentsWeb.ThreadControllerTest`.

### METER-001 — A cost is reported only where a price exists, and never as zero

  `unpriced_calls/1` is above zero; `balance/1` publishes `complete?` so no

  reader shows a balance as whole when it is not.

Amended 2026-08-25 (#250): a record is priced against the model that **served**

the call, never the one that was asked for. The two are not always the same

name. `config :openagents, :vercel_gateway_fallback_models` instructs the

Vercel AI Gateway to answer a failed `google/gemini-3.7-flash` call with

`openai/gpt-5.6-luna` and return 200, and the adapter did not read back which

model answered — so a Luna call was priced at Gemini's rates and produced

`$2.25` of measured-looking cost from a lane this deployment has no rates for.

So every metered record also names its lane. `served_model` is read off the

response's own `model` field, carried out of the chat-completions decoder as

`{:model_served, name}`, and written as the catalog id where the catalog serves

that model. Three values are not model names and none of them resolves to a

rate table, so all three price at nothing:

- `unresolved` — the lane may substitute (`Provider.substitutable?/0`, true for

  the gateway exactly while a fallback list is configured) and the response

  disclosed no model. Naming the requested model here would be a claim the

  deployment cannot support.

- `mixed` — one grant's calls were served by more than one model. A single

  accumulated total cannot be charged at two rate tables, and picking one would

  be a guess.

- any model outside the catalog — a fallback the operator never priced.

`OpenAgents.Threads.spend/1` reports the serving lane in `cost.unpriced_models`

rather than the requested one, so an operator is sent to price the lane that

actually ran. A lane that cannot be substituted for needs no disclosure: it

gets the model it asked for or an error, so its silence still means the grant's

model.

An unpriced lane is not a free lane and not an error. It is the deployment

saying it does not know what a call cost, which is a different fact from the

call having cost nothing, and the distinction survives to every read surface.

Evidence: `OpenAgents.Inference.Pricing`, `OpenAgents.Inference.PricingTest`,

`OpenAgents.Inference.CreditTest`, `OpenAgents.ThreadsTest`,

`OpenAgentsWeb.ModelCatalogControllerTest`,

`OpenAgentsWeb.ThreadControllerTest`, `OpenAgentsWeb.ThreadShowLiveTest`, and

`OpenAgentsWeb.ModelCatalogLiveTest`.

`OpenAgentsWeb.ThreadControllerTest`, `OpenAgentsWeb.ThreadShowLiveTest`,

`OpenAgentsWeb.ModelCatalogLiveTest`,

`OpenAgentsWeb.InferenceProxyFallbackTest`, and

`OpenAgents.Providers.OpenRouter.StreamDecoderTest`.

## Durable effects

| TURN-005 | `test/openagents/turn_tool_loop_test.exs` |

| PROVENANCE-001 | `test/openagents/turn_provenance_test.exs` |

| PROVIDER-001 | `test/openagents/providers/provider_contract_test.exs`, `test/openagents/turn_provider_events_test.exs`, `test/openagents/dependency_boundary_test.exs` |

| PROVIDER-002 | `test/openagents/inference/models_test.exs`, `test/openagents_web/controllers/model_catalog_controller_test.exs`, `test/openagents_web/controllers/inference_proxy_controller_test.exs`, `test/openagents_web/controllers/thread_controller_test.exs` |

| METER-001 | `test/openagents/inference/pricing_test.exs`, `test/openagents/inference/credit_test.exs`, `test/openagents/threads_test.exs`, `test/openagents_web/controllers/model_catalog_controller_test.exs`, `test/openagents_web/controllers/thread_controller_test.exs`, `test/openagents_web/live/thread_show_live_test.exs`, `test/openagents_web/live/model_catalog_live_test.exs` |

| PROVIDER-002 | `test/openagents/inference/models_test.exs`, `test/openagents_web/controllers/model_catalog_controller_test.exs`, `test/openagents_web/controllers/inference_proxy_controller_test.exs`, `test/openagents_web/controllers/inference_proxy_fallback_test.exs`, `test/openagents_web/controllers/thread_controller_test.exs` |

| METER-001 | `test/openagents/inference/pricing_test.exs`, `test/openagents/inference/credit_test.exs`, `test/openagents/threads_test.exs`, `test/openagents_web/controllers/model_catalog_controller_test.exs`, `test/openagents_web/controllers/thread_controller_test.exs`, `test/openagents_web/controllers/inference_proxy_fallback_test.exs`, `test/openagents/providers/open_router/stream_decoder_test.exs`, `test/openagents_web/live/thread_show_live_test.exs`, `test/openagents_web/live/model_catalog_live_test.exs` |

| EFFECT-001 | `test/openagents/effects_test.exs`, `test/openagents/effects/work_launch_test.exs` |

| EFFECT-002 | `test/openagents/effects_test.exs`, `test/openagents/effects/work_launch_test.exs` |

| TOOL-001 | `test/openagents/tools/registry_and_runner_test.exs` |

  token usage, prices it, increments the call count, and flips the grant to

  `exhausted` when any ceiling is reached — atomically, re-reading under a row

  lock so concurrent calls cannot exceed the budget.

  `served` names the model that actually answered, because the grant's model is

  what was asked for and the two are not always the same name. `:requested`

  says the lane cannot be substituted for, so the grant's model served it.

  `:unresolved` says the lane can be substituted for and the response did not

  disclose what answered, which is priced at nothing rather than at the

  requested model's rate. A binary is the serving model's own name (METER-001).

  """

  @spec record_usage(Grant.t(), map()) :: {:ok, Grant.t()} | {:error, term()}

  def record_usage(%Grant{id: id}, provider_usage) when is_map(provider_usage) do

  def record_usage(%Grant{} = grant, provider_usage) when is_map(provider_usage),

    do: record_usage(grant, provider_usage, :requested)

  @spec record_usage(Grant.t(), map(), :requested | :unresolved | String.t()) ::

          {:ok, Grant.t()} | {:error, term()}

  def record_usage(%Grant{id: id}, provider_usage, served)

      when is_map(provider_usage) and (served in [:requested, :unresolved] or is_binary(served)) do

    Repo.transaction(fn ->

      grant =

        Grant

      case grant do

        %Grant{status: "active"} = grant ->

          merged = merge_usage(grant.usage, provider_usage, grant.model_id)

          merged = merge_usage(grant.usage, provider_usage, served_name(served, grant.model_id))

          would_exhaust = would_exhaust?(grant, merged)

          next_status = if would_exhaust, do: "exhausted", else: "active"

  @cost_fields ~w(input_tokens output_tokens total_tokens reasoning_tokens

                  cache_read_input_tokens cache_write_input_tokens)

  @doc false

  def merge_usage(existing, provider_usage, model_id) do

  # The two names a usage record's `served_model` can carry that are not a

  # model. Neither resolves in the catalog, so `Pricing.price/2` prices both at

  # nothing — which is the point: an unknown is not a rate.

  @unresolved_model "unresolved"

  @mixed_model "mixed"

  @doc "What a usage record's `served_model` says when the provider disclosed nothing."

  @spec unresolved_model() :: String.t()

  def unresolved_model, do: @unresolved_model

  @doc "What a usage record's `served_model` says when more than one model served it."

  @spec mixed_model() :: String.t()

  def mixed_model, do: @mixed_model

  defp served_name(:requested, model_id), do: model_id

  defp served_name(:unresolved, _model_id), do: @unresolved_model

  defp served_name(name, _model_id) when is_binary(name), do: name

  @doc """

  Merge one call's provider usage into a grant's record and price the total.

  `served_model_name` is the model that answered this call. A record is priced

  against the model that served it, never against the one that was asked for,

  and a record whose calls were served by more than one model is priced at

  nothing: a single total cannot be charged at two rates, and picking one would

  be a guess (METER-001).

  """

  @spec merge_usage(map() | nil, map(), String.t() | nil) :: map()

  def merge_usage(existing, provider_usage, served_model_name) do

    normalized = normalize_usage(provider_usage)

    served = served_model(existing, served_model_name)

    merged =

      Enum.reduce(@cost_fields, %{}, fn field, acc ->

    merged

    |> Map.put("total_tokens", derived_total(existing, merged))

    |> Pricing.price(model_id)

    |> Map.put("served_model", served)

    |> Pricing.price(served)

    |> Map.put("schema", @usage_schema)

  end

  # The model a record says served it. A record already naming one model that

  # a later call did not use becomes `mixed`, because the accumulated total is

  # then a sum across two rate tables and no single one prices it.

  #

  # A record written before this key existed names nothing, so the first call

  # after that names the model that served it. That is the honest reading:

  # nothing recorded which model served the earlier calls, and inventing an

  # agreement in order to keep a price would be the failure this exists to

  # prevent.

  defp served_model(existing, name) do

    name = canonical_model(name)

    case Map.get(existing || %{}, "served_model") do

      nil -> name

      ^name -> name

      _different -> @mixed_model

    end

  end

  # One model, one name. A provider reports the vendor spelling

  # (`google/gemini-3.7-flash`) and a grant may carry either, so both are

  # written as the catalog id — otherwise two spellings of one model would read

  # as two models and make a record `mixed` that never left its lane. A name

  # the catalog does not serve stays as it came, which is exactly the case that

  # prices at nothing.

  defp canonical_model(nil), do: @unresolved_model

  defp canonical_model(name) when is_binary(name) do

    case Models.fetch(name) do

      {:ok, %{id: id}} -> id

      :error -> name

    end

  end

  defp derived_total(existing, merged) do

    explicit = integer(merged["total_tokens"])

  @identifier_regex ~r/\A[a-zA-Z0-9_.:\/-]+\z/

  @tool_name_regex ~r/\A[a-zA-Z0-9_-]+\z/

  defstruct buffer: "", response_id: nil, terminal?: false, failed?: false, calls: %{}

  defstruct buffer: "",

            response_id: nil,

            served_model: nil,

            terminal?: false,

            failed?: false,

            calls: %{}

  @type t :: %__MODULE__{

          buffer: String.t(),

          response_id: String.t() | nil,

          served_model: String.t() | nil,

          terminal?: boolean(),

          failed?: boolean(),

          calls: %{optional(integer()) => map()}

  defp decode_json(state, {:ok, %{} = chunk}) do

    with {:ok, state, start_events} <- start_response(state, chunk["id"]),

         {:ok, state, model_events} <- served_model(state, chunk["model"]),

         {:ok, state, choice_events} <- choices(state, chunk["choices"]),

         {:ok, usage_events} <- usage(chunk["usage"]) do

      {:ok, state, start_events ++ choice_events ++ usage_events}

      {:ok, state, start_events ++ model_events ++ choice_events ++ usage_events}

    end

  end

  defp start_response(%__MODULE__{} = state, _response_id), do: {:ok, state, []}

  # Every chat-completions chunk names the model that produced it, and that

  # name is not always the one the request asked for: the Vercel AI Gateway is

  # configured with a fallback list, so a call for `google/gemini-3.7-flash`

  # can come back served by `openai/gpt-5.6-luna`. Reading the field back is

  # the only way the host learns which lane to price and attribute the call

  # against, so it is carried out as an event rather than dropped.

  #

  # Reported once. A chunk whose model is missing or unreadable reports

  # nothing rather than a guess, and the host treats silence from a

  # substitutable adapter as unresolved rather than as the requested model.

  defp served_model(%__MODULE__{served_model: nil} = state, model) do

    if valid_identifier?(model) do

      {:ok, %{state | served_model: model}, [{:model_served, model}]}

    else

      {:ok, state, []}

    end

  end

  defp served_model(%__MODULE__{} = state, _model), do: {:ok, state, []}

  defp usage(nil), do: {:ok, []}

  defp usage(usage) when is_map(usage) do

  """

  @callback configured?() :: boolean()

  @optional_callbacks configured?: 0

  @doc """

  Whether this adapter may have its request answered by a model other than the

  one it asked for.

  Optional, and `false` where it is not exported: an adapter that calls one

  vendor with one model gets that model or an error. It is `true` only where

  the deployment has configured the lane to substitute — the Vercel AI Gateway

  with a fallback model list — and the answer bounds what silence means. A

  substitutable adapter whose response does not disclose the serving model has

  not told the host what answered, so the host records the model as unresolved

  and prices nothing, rather than recording the requested model as though it

  served (METER-001).

  """

  @callback substitutable?() :: boolean()

  @optional_callbacks configured?: 0, substitutable?: 0

  @callback stream(

              OpenAgents.Providers.Request.t(),

defmodule OpenAgents.Providers.ProviderEvent do

  @moduledoc "Provider-neutral lifecycle and content events consumed by Sarah's turn runtime."

  @moduledoc """

  Provider-neutral lifecycle and content events consumed by Sarah's turn runtime.

  `{:model_served, name}` is what the provider said answered, read back off the

  response rather than assumed from the request. It exists because a request

  and its answer can name different models: the Vercel AI Gateway is configured

  with a fallback list, and a primary that fails is replaced by another model

  without the request being refused. An adapter that can be substituted for

  emits this so the host prices and attributes the call against the model that

  actually served it (METER-001, PROVIDER-002).

  """

  defmodule ToolCall do

    @moduledoc "A provider-requested function call awaiting host admission and validation."

  @type t ::

          {:response_started, String.t()}

          | {:model_served, String.t()}

          | {:text_delta, String.t()}

          | {:reasoning_delta, String.t()}

          | {:tool_call, ToolCall.t()}

  where the credits are. `providerOptions.gateway.models` lists the fallback

  models Vercel tries if the primary model fails.

  That list is why this lane reports `substitutable?/0` as true: a call for

  `google/gemini-3.7-flash` can be answered by `openai/gpt-5.6-luna` and still

  return 200, so the model that was asked for is not evidence of the model that

  answered. The response's `model` field is, and the chat-completions decoder

  reads it back as `{:model_served, name}` so the call is priced and attributed

  against the lane that served it rather than the lane that was requested

  (METER-001, PROVIDER-002).

  The wire format is OpenRouter's, so the request building and the stream

  decoding are OpenRouter's too. What differs is the endpoint, the credential,

  and the pin.

    match?({:ok, _key}, OpenAgents.RuntimeConfig.fetch_secret(:vercel_gateway_api_key))

  end

  @doc """

  Whether a call on this lane may be answered by a different model.

  True exactly while a fallback list is configured. `providerOptions.gateway.models`

  is an instruction to Vercel to try another model when the primary fails, so a

  request for `google/gemini-3.7-flash` can be answered by `openai/gpt-5.6-luna`

  and return 200. The host reads the serving model back off the response; this

  says what its silence means, because a lane that cannot be substituted for

  needs no disclosure to be attributed correctly.

  """

  @impl true

  def substitutable?, do: fallback_models() != []

  @impl true

  def stream(%Request{} = request, on_event) when is_function(on_event, 1) do

    stream(request, on_event, [])

    |> Keyword.put(:payload_extra, payload_extra())

  end

  @doc "The models Vercel may try when the requested one fails."

  @spec fallback_models() :: [String.t()]

  def fallback_models do

    case Application.get_env(:openagents, :vercel_gateway_fallback_models, []) do

      models when is_list(models) -> models

      _not_a_list -> []

    end

  end

  @doc false

  def payload_extra do

    providers = Application.get_env(:openagents, :vercel_gateway_providers, [])

    fallbacks = Application.get_env(:openagents, :vercel_gateway_fallback_models, [])

    fallbacks = fallback_models()

    gateway =

      %{}

    unpriced_calls = Enum.sum(Enum.map(unpriced, fn {calls, _usage, _model} -> calls end))

    # The lane named here is the one that made the total unknown, which is the

    # model that served the call rather than the model the grant asked for.

    # A gateway fallback answers a request for one model with another, and

    # naming the requested lane would send an operator to price a lane that was

    # already priced (METER-001).

    unpriced_models =

      unpriced

      |> Enum.map(fn {_calls, _usage, model_id} -> model_id end)

      |> Enum.map(fn {_calls, usage, model_id} ->

        Map.get(usage || %{}, "served_model") || model_id

      end)

      |> Enum.reject(&is_nil/1)

      |> Enum.uniq()

      |> Enum.sort()

  Every 200 attributes the effective model — the `x-openagents-model` header

  and each chunk's `model` field — so a client renders what answered.

  What answered is read back off the response rather than assumed from the

  request. One lane can substitute: the Vercel AI Gateway is configured with a

  fallback model list, so a call for `google/gemini-3.7-flash` can be served by

  `openai/gpt-5.6-luna` and still return 200. The serving model therefore

  decides three things — the name attributed on the response, the lane whose

  health is recorded, and the rate table the usage record is priced against

  (METER-001). A substitutable lane whose response discloses no model is

  attributed `unresolved` and priced at nothing, because naming the requested

  model would be a claim the deployment cannot support.

  The probe→proxy hop is buffered (the provider still streams from the vendor

  internally); probe's transport reads the whole body before parsing, so this

  matches its consumer and keeps failure handling honest.

    case result do

      :ok ->

        # What answered is read back off the response, never assumed from the

        # request: a gateway lane configured with fallback models can serve a

        # call for one model with another and still return 200 (METER-001).

        served = served_model(model, events)

        usage = usage_of(events)

        _ = meter(grant, usage)

        _ = meter(grant, usage, served)

        record_health(model, served)

        # The effective model is attributed on the response itself — the

        # header and every chunk's `model` field — so a client renders what

        # answered, not what it assumed (PROVIDER-002). Because a mismatched

        # request was refused above, requested and effective are the same

        # name on every 200.

        OpenAgents.Inference.Health.record_success(model.id)

        # answered, not what it assumed (PROVIDER-002).

        label = model_label(model, served)

        conn

        |> put_resp_content_type("text/event-stream")

        |> put_resp_header("cache-control", "no-store")

        |> put_resp_header("x-openagents-model", model.id)

        |> send_resp(200, sse_body(events, model.id))

        |> put_resp_header("x-openagents-model", label)

        |> send_resp(200, sse_body(events, label))

      {:error, reason} ->

        # A failure that produced partial usage is still metered; the probe

        # sees a provider error, never raw provider detail.

        # A failure that produced partial usage is still metered, against

        # whatever the partial response said was serving it — the tokens were

        # spent on that model whether or not the stream finished.

        usage = usage_of(events)

        if usage != %{}, do: meter(grant, usage)

        if usage != %{}, do: meter(grant, usage, served_model(model, events))

        class = OpenAgents.OperationalLog.code(reason)

        status = OpenAgents.OperationalLog.status(reason)

        # What the catalog publishes about this lane follows from what it

    end

  end

  defp meter(grant, usage) when usage == %{}, do: {:ok, grant}

  defp meter(grant, usage), do: Inference.record_usage(grant, usage)

  defp meter(grant, usage, _served) when usage == %{}, do: {:ok, grant}

  defp meter(grant, usage, served), do: Inference.record_usage(grant, usage, served)

  # Which model actually served this call.

  #

  # `:requested` where the response named the model the grant pins, and where a

  # lane that cannot be substituted for named nothing — such a lane gets the

  # model it asked for or an error, so silence there is not ambiguity.

  # `:unresolved` where a lane that *can* be substituted for named nothing: the

  # deployment does not know what answered, and saying the requested model

  # would be a claim it cannot support. Otherwise the name the provider gave.

  defp served_model(model, events) do

    case Enum.find_value(events, fn

           {:model_served, name} -> name

           _event -> nil

         end) do

      name when is_binary(name) ->

        case Models.fetch(name) do

          {:ok, %{id: id}} when id == model.id -> :requested

          _other_or_unserved -> name

        end

      nil ->

        if substitutable?(model.adapter), do: :unresolved, else: :requested

    end

  end

  defp substitutable?(adapter) do

    Code.ensure_loaded?(adapter) and function_exported?(adapter, :substitutable?, 0) and

      adapter.substitutable?()

  end

  # Health is a claim about a lane, so it follows the lane that answered.

  #

  # A fallback that rescued a call is not evidence that the requested lane is

  # working — it is evidence that it is not, which is exactly what `GET

  # /api/v1/models` availability exists to publish (#238). An unresolved

  # response records nothing at all: it says neither that the lane answered nor

  # that it failed, and health that reports what it does not know is the fault

  # being fixed rather than a smaller version of it.

  defp record_health(model, :requested), do: OpenAgents.Inference.Health.record_success(model.id)

  defp record_health(_model, :unresolved), do: :ok

  defp record_health(model, name) when is_binary(name) do

    OpenAgents.Inference.Health.record_failure(model.id, nil)

    case Models.fetch(name) do

      {:ok, %{id: id}} -> OpenAgents.Inference.Health.record_success(id)

      :error -> :ok

    end

  end

  # The name the response carries. A model the catalog serves is named as a

  # client would ask for it; one it does not is named as the provider reported

  # it; and where nothing disclosed what answered, the word `unresolved` says

  # so rather than naming a model that may not have run.

  defp model_label(model, :requested), do: model.id

  defp model_label(_model, :unresolved), do: Inference.unresolved_model()

  defp model_label(_model, name) when is_binary(name) do

    case Models.fetch(name) do

      {:ok, %{id: id}} -> id

      :error -> name

    end

  end

  defp usage_of(events) do

    Enum.reduce(events, %{}, fn

    assert StreamDecoder.finish(decoder) == {:error, :truncated_stream}

  end

  # METER-001, PROVIDER-002. The Vercel gateway shares this decoder, and its

  # fallback list means the model that answers is not always the model that was

  # asked for. The `model` field is the only place the answer says which one

  # ran, so dropping it left the host pricing a Luna call at Gemini's rates.

  test "reports the model the response says served it, once" do

    stream =

      frame(%{

        "id" => "gen-f",

        "model" => "openai/gpt-5.6-luna",

        "choices" => [%{"delta" => %{"content" => "Hi"}}]

      }) <>

        frame(%{

          "id" => "gen-f",

          "model" => "openai/gpt-5.6-luna",

          "choices" => [%{"delta" => %{}, "finish_reason" => "stop"}]

        }) <> "data: [DONE]\n\n"

    assert {:ok, decoder, events} = feed_in_pieces(stream, 11)

    assert {:ok, _decoder, final} = StreamDecoder.finish(decoder)

    assert events ++ final == [

             {:response_started, "gen-f"},

             {:model_served, "openai/gpt-5.6-luna"},

             {:text_delta, "Hi"},

             {:response_completed, "gen-f"}

           ]

  end

  test "reports no served model where the response names none" do

    stream =

      frame(%{"id" => "gen-s", "choices" => [%{"delta" => %{"content" => "Hi"}}]}) <>

        frame(%{"id" => "gen-s", "choices" => [%{"delta" => %{}, "finish_reason" => "stop"}]}) <>

        "data: [DONE]\n\n"

    assert {:ok, decoder, events} = feed_in_pieces(stream, 9)

    assert {:ok, _decoder, final} = StreamDecoder.finish(decoder)

    refute Enum.any?(events ++ final, &match?({:model_served, _}, &1))

  end

  test "refuses a frame that is not JSON" do

    assert StreamDecoder.feed(StreamDecoder.new(), "data: {not json\n\n") ==

             {:error, :invalid_provider_event}

    OpenAgents.Providers.OpenAI => :outbound_http,

    OpenAgents.Providers.OpenRouter => :outbound_http,

    OpenAgents.Providers.VercelGateway => :outbound_http,

    OpenAgents.Providers.FallbackTestProvider => :in_process,

    OpenAgents.Providers.RecordingTestProvider => :in_process,

    OpenAgents.Providers.Test => :in_process,

    OpenAgents.Providers.UnconfiguredTestProvider => :in_process,

    OpenAgents.Providers.OpenAI => :adapter,

    OpenAgents.Providers.OpenRouter => :adapter,

    OpenAgents.Providers.VercelGateway => :adapter,

    OpenAgents.Providers.FallbackTestProvider => :adapter,

    OpenAgents.Providers.RecordingTestProvider => :adapter,

    OpenAgents.Providers.Test => :adapter,

    OpenAgents.Providers.Request => :the_struct_itself

    end

  end

  # METER-001, PROVIDER-002. The fallback list is an instruction to answer a

  # failed call with a different model, so this lane's request is not evidence

  # of what served it. Saying so is what makes the host read an undisclosed

  # model as unresolved rather than as the model it asked for.

  describe "whether this lane can be substituted for" do

    setup do

      previous = Application.get_env(:openagents, :vercel_gateway_fallback_models)

      on_exit(fn ->

        Application.put_env(:openagents, :vercel_gateway_fallback_models, previous)

      end)

      :ok

    end

    test "is true exactly while a fallback list is configured" do

      Application.put_env(:openagents, :vercel_gateway_fallback_models, ["openai/gpt-5.6-luna"])

      assert VercelGateway.substitutable?()

      Application.put_env(:openagents, :vercel_gateway_fallback_models, [])

      refute VercelGateway.substitutable?()

    end

  end

  describe "the credential" do

    test "is its own, not OpenRouter's" do

      previous = Application.get_env(:openagents, :vercel_gateway_api_key)

defmodule OpenAgentsWeb.InferenceProxyFallbackTest do

  @moduledoc """

  What a metered call says when a fallback served it.

  `config :openagents, :vercel_gateway_fallback_models` tells Vercel to answer a

  failed `google/gemini-3.7-flash` call with `openai/gpt-5.6-luna` and still

  return 200. The adapter never read back which model answered, so the usage

  record was priced against Gemini's rates for a call Luna served, the thread's

  cost totalled as though it were known, and the Gemini lane was recorded

  healthy on the strength of a call it did not serve (METER-001, PROVIDER-002).

  """

  use OpenAgentsWeb.ConnCase, async: false

  alias OpenAgents.Inference

  alias OpenAgents.Inference.Grant

  alias OpenAgents.Inference.Health

  alias OpenAgents.Inference.Models

  alias OpenAgents.Inference.Pricing

  alias OpenAgents.Repo

  alias OpenAgents.Threads

  @gemini "gemini-3.7-flash"

  setup do

    previous = Application.get_env(:openagents, :vercel_gateway_provider)

    Application.put_env(

      :openagents,

      :vercel_gateway_provider,

      OpenAgents.Providers.FallbackTestProvider

    )

    Health.reset()

    on_exit(fn ->

      Application.put_env(:openagents, :vercel_gateway_provider, previous)

      Application.delete_env(:openagents, :test_fallback_served_model)

      Health.reset()

    end)

    :ok

  end

  defp serve_as(name), do: Application.put_env(:openagents, :test_fallback_served_model, name)

  defp disclose_nothing, do: Application.delete_env(:openagents, :test_fallback_served_model)

  defp gemini_grant(key) do

    owner = github_user("fallback-#{key}")

    {:ok, conversation} = OpenAgents.Conversations.ensure_conversation(owner)

    {:ok, grant, token} =

      Inference.mint(%{

        owner_visitor_id: conversation.visitor_id,

        conversation_id: conversation.id,

        model_id: @gemini

      })

    %{grant: grant, token: token}

  end

  defp call(conn, token) do

    conn

    |> put_req_header("authorization", "Bearer #{token}")

    |> put_req_header("content-type", "application/json")

    |> post(

      ~p"/api/inference/proxy",

      Jason.encode!(%{"messages" => [%{"role" => "user", "content" => "hello"}]})

    )

  end

  describe "a call a fallback model served" do

    test "is priced against the model that served it, not the one requested", %{conn: conn} do

      # The requested lane has rates; the lane Vercel fell back to has none.

      # Pricing the call at the requested lane's rates is the bug: it produces

      # a figure, and the figure is for a call that never ran there.

      assert Pricing.basis(@gemini) == "provisional"

      serve_as("openai/gpt-5.6-luna")

      %{grant: grant, token: token} = gemini_grant("priced")

      assert call(conn, token).status == 200

      metered = Repo.get(Grant, grant.id)

      assert metered.usage["served_model"] == "openai/gpt-5.6-luna"

      assert metered.usage["pricing_id"] == Pricing.unpriced()

      refute Map.has_key?(metered.usage, "estimated_cost_microusd")

      assert Pricing.cost(metered.usage) == nil

    end

    test "is attributed to the model that served it on the response", %{conn: conn} do

      serve_as("openai/gpt-5.6-luna")

      %{token: token} = gemini_grant("attributed")

      conn = call(conn, token)

      assert get_resp_header(conn, "x-openagents-model") == ["openai/gpt-5.6-luna"]

      for chunk <- String.split(conn.resp_body, "\n\n", trim: true),

          chunk != "data: [DONE]" do

        payload = chunk |> String.replace_prefix("data: ", "") |> Jason.decode!()

        assert payload["model"] == "openai/gpt-5.6-luna"

      end

    end

    test "counts against the requested lane's health, not for it", %{conn: conn} do

      # `GET /api/v1/models` publishes availability from this. A lane that was

      # rescued by a fallback did not answer, and recording it healthy is the

      # same class of lie that #238 fixed: every call to a dead lane would keep

      # reporting `available` forever, because the fallback kept rescuing it.

      luna = Application.fetch_env!(:openagents, :openai_model)

      serve_as(luna)

      {:ok, gemini} = Models.fetch(@gemini)

      for index <- 1..Health.degraded_after() do

        %{token: token} = gemini_grant("health-#{index}")

        assert call(conn, token).status == 200

      end

      assert Models.availability(gemini) == "degraded"

      assert Health.status(luna) == {:healthy, nil}

    end

    test "makes the thread's cost unpriced, and names the lane that made it so", %{conn: _conn} do

      # METER-001's contract, end to end: a thread whose only call was served

      # by an unpriced fallback reports no total at all rather than a total at

      # the requested model's rates.

      user = github_user("fallback-thread")

      {:ok, thread, grant, _token} = Threads.open_and_mint(user, "Fallback lane")

      assert grant.model_id == @gemini

      {:ok, _metered} =

        Inference.record_usage(

          grant,

          %{"input_tokens" => 1_000_000, "output_tokens" => 100_000},

          "openai/gpt-5.6-luna"

        )

      spend = Threads.spend(thread)

      assert spend.calls == 1

      refute spend.cost.microusd == 0

      assert spend.cost.microusd == nil

      assert spend.cost.basis == "unpriced"

      assert spend.cost.unpriced_calls == 1

      assert spend.cost.unpriced_models == ["openai/gpt-5.6-luna"]

    end

  end

  describe "a call whose serving model the response did not disclose" do

    test "is recorded unresolved and priced at nothing", %{conn: conn} do

      disclose_nothing()

      %{grant: grant, token: token} = gemini_grant("silent")

      conn = call(conn, token)

      assert conn.status == 200

      metered = Repo.get(Grant, grant.id)

      # The lane can substitute and the answer said nothing, so what served it

      # is unknown. Recording the requested model here would be inventing the

      # one fact the record exists to carry.

      assert metered.usage["served_model"] == Inference.unresolved_model()

      assert metered.usage["pricing_id"] == Pricing.unpriced()

      refute Map.has_key?(metered.usage, "estimated_cost_microusd")

      assert get_resp_header(conn, "x-openagents-model") == [Inference.unresolved_model()]

    end

    test "records no health for the requested lane either way", %{conn: conn} do

      disclose_nothing()

      %{token: token} = gemini_grant("silent-health")

      assert call(conn, token).status == 200

      # Neither healthy nor degraded: nothing here knows whether that lane ran.

      assert Health.status(@gemini) == {:unknown, nil}

    end

  end

  describe "a call the requested model served" do

    test "is priced and attributed as it always was, by either spelling", %{conn: conn} do

      # The gateway names the vendor spelling; the catalog names the public id.

      # They are one model, and reading them as two would make every Gemini

      # call unpriced.

      {:ok, gemini} = Models.fetch(@gemini)

      serve_as(gemini.provider_model)

      %{grant: grant, token: token} = gemini_grant("same")

      conn = call(conn, token)

      assert get_resp_header(conn, "x-openagents-model") == [@gemini]

      metered = Repo.get(Grant, grant.id)

      assert metered.usage["served_model"] == @gemini

      assert metered.usage["pricing_id"] == "placeholder.gemini-3.7-flash.v1"

      assert Pricing.cost(metered.usage) > 0

      assert Health.status(@gemini) == {:healthy, nil}

    end

  end

  describe "a grant whose calls were served by more than one model" do

    test "reports a mixed record and no total" do

      # Two rate tables, one accumulated sum. Charging it at either rate would

      # be a guess, so the record says so and prices nothing.

      user = github_user("fallback-mixed")

      {:ok, _thread, grant, _token} = Threads.open_and_mint(user, "Mixed lanes")

      {:ok, first} = Inference.record_usage(grant, %{"input_tokens" => 1_000}, :requested)

      assert first.usage["served_model"] == @gemini

      assert Pricing.cost(first.usage) > 0

      {:ok, second} =

        Inference.record_usage(first, %{"input_tokens" => 1_000}, "openai/gpt-5.6-luna")

      assert second.usage["served_model"] == Inference.mixed_model()

      assert second.usage["pricing_id"] == Pricing.unpriced()

      assert Pricing.cost(second.usage) == nil

    end

  end

  test "the reserved names are not names the catalog could serve" do

    # `unresolved` and `mixed` price at nothing because the catalog does not

    # resolve them. A model that took either name would be priced by accident.

    reserved = [Inference.unresolved_model(), Inference.mixed_model()]

    for model <- Models.all() do

      refute model.id in reserved

      refute model.provider_model in reserved

    end

  end

end

defmodule OpenAgents.Providers.FallbackTestProvider do

  @moduledoc false

  @behaviour OpenAgents.Providers.Provider

  alias OpenAgents.Providers.Request

  @impl true

  def id, do: "test.fallback_provider"

  @impl true

  def capabilities, do: [:text, :usage]

  @impl true

  def configured?, do: true

  # Stands in for the Vercel AI Gateway lane with a fallback model list: the

  # model that answers is not necessarily the model that was asked for.

  @impl true

  def substitutable?, do: true

  @doc """

  Emit one response, optionally disclosing which model served it.

  `config :openagents, :test_fallback_served_model` is the name the response

  carries. Anything that is not a binary — the default — is a response that

  discloses nothing, which is the case the host must read as unresolved rather

  than as the requested model.

  """

  @impl true

  def stream(%Request{}, on_event) when is_function(on_event, 1) do

    on_event.({:response_started, "fallback-response"})

    case Application.get_env(:openagents, :test_fallback_served_model) do

      name when is_binary(name) -> on_event.({:model_served, name})

      _undisclosed -> :ok

    end

    on_event.({:text_delta, "Served."})

    on_event.({:usage, %{"input_tokens" => 4, "output_tokens" => 8}})

    on_event.({:response_completed, "fallback-response"})

    :ok

  end

end