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.

  `config :openagents, :vercel_gateway_fallback_models` is set **and the call

  did not name a model**, 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-27 (#258): a grant that named a model is a pin. The proxy

  does not send `providerOptions.gateway.models` on that call; the Vertex

  `order` pin stays. Fallback remains only for unnamed-model selection

  (neither the mint nor the call named a model). If the gateway still

  substitutes on a pinned grant, the proxy does not return 200: the serving

  model must be the grant's public id or that entry's `provider_model`, or

  the call is a typed `model_substituted` refusal.

- 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

  `providerOptions.gateway.order` tries Vertex first, because the same slug is

  also served by `google` — the Generative Language endpoint, which is not

  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 `zai/glm-5.3` and still return

  models Vercel tries if the primary model fails, and it is attached only when

  the call allows fallback: unnamed-model selection. A grant that named a

  model is a pin (`allow_fallback: false`); that call keeps the Vertex `order`

  and omits the fallback list, so Vercel is not asked to answer with another

  model.

  The configured list is why this lane reports `substitutable?/0` as true: a

  call that *does* send it — unnamed-model selection for

  `google/gemini-3.7-flash` — can be answered by `zai/glm-5.3` 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).

  (METER-001, PROVIDER-002). A pinned grant whose response names another model

  is refused by the proxy rather than returned as 200.

  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,

  defp gateway_options(options) do

    options

    |> Keyword.put(:endpoint, @endpoint)

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

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

  end

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

  end

  @doc false

  def payload_extra do

  def payload_extra(options \\ []) when is_list(options) do

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

    fallbacks = fallback_models()

    # A pin must not send the fallback list: Vercel treats `gateway.models` as

    # permission to answer with another model and still return 200 (#258).

    fallbacks =

      if Keyword.get(options, :allow_fallback, true), do: fallback_models(), else: []

    gateway =

      %{}

  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

  `zai/glm-5.3` 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.

  request. One lane can substitute, and only where nothing named a model: the

  Vercel AI Gateway is configured with a fallback model list, and unnamed-model

  selection attaches it, so a call that asked for whatever this deployment

  serves can be answered by `zai/glm-5.3` and still return 200. A grant that

  named a model is a pin. That call omits the fallback list and keeps the

  Vertex `order` pin; if the gateway still substitutes, the proxy does not

  return 200 (PROVIDER-002). 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 unnamed call 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 stream is flushed as it happens

  # since been withdrawn — is refused here rather than sent to a provider that

  # does not serve it.

  defp route(grant, body) do

    if no_model_in_body?(body) and grant.model_id == Models.default_id() do

    if unnamed_selection?(grant, body) do

      {:ok, Models.select()}

    else

      case Models.fetch(grant.model_id) do

    end

  end

  # Neither the mint nor the call named a model: the server selects, and the

  # gateway may still try its fallback list. A grant minted for a model other

  # than the default, or a body that names one, is a pin (#258).

  defp unnamed_selection?(grant, body) do

    no_model_in_body?(body) and grant.model_id == Models.default_id()

  end

  defp no_model_in_body?(body) do

    case Map.get(body, "model") do

      absent when absent in [nil, ""] -> true

  @state_usage :proxy_stream_usage

  @state_served :proxy_stream_served_model

  @state_conn :proxy_stream_conn

  @state_raw_conn :proxy_stream_raw_conn

  @state_opened :proxy_stream_opened

  @state_allow_fallback :proxy_stream_allow_fallback

  defp run(conn, grant, model, request) do

    allow_fallback? = unnamed_selection?(grant, conn.body_params)

    selection = selection_properties(grant, model, request, conn.body_params)

    Analytics.capture("inference_model_selected", analytics_distinct_id(grant), selection)

    # The stream opens before the first provider event, so the status and the

    # model attribution commit early. The header names the grant's lane; a

    # fallback that answered under another name still corrects every chunk and

    # the final attribution exactly as it did when the whole body was written

    # at the end.

    conn =

      conn

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

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

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

      |> send_chunked(200)

    Process.put(@state_conn, conn)

    # The provider pushes events synchronously, and each one is translated and

    # written to the client as it arrives (#263): a reasoning or text token

    # reaches the caller while the vendor is still producing the next one.

    result = model.adapter.stream(request, &emit_event(conn, model, &1))

    Process.put(@state_raw_conn, conn)

    Process.put(@state_allow_fallback, allow_fallback?)

    # Unnamed-model selection may still be answered by a fallback, so the

    # stream opens before the first provider event (#263). A pin waits until

    # the serving model is known: opening 200 first would make a substituted

    # grant look like a successful turn (#258).

    if allow_fallback?, do: open_stream(model)

    # The provider pushes events synchronously. Once the stream is open, each

    # event is translated and written to the client as it arrives.

    result =

      stream_adapter(model.adapter, request, &emit_event(conn, model, &1),

        allow_fallback: allow_fallback?

      )

    case result do

      :ok ->

        events = drained_events()

        # 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).

        # request. Unnamed-model selection may still land on a fallback and

        # return 200 (METER-001). A pin must be the grant's model.

        served = served_model(model, events)

        usage = drained_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).

        label = model_label(model, served)

        Analytics.capture(

          "inference_model_served",

          analytics_distinct_id(grant),

          Map.merge(selection, %{

            "served_model" => label,

            "served_model_disclosed" => served != :unresolved,

            "outcome" => "served",

            "usage_reported" => usage != %{}

          })

        )

        Enum.each(sse_chunks(events, usage, label), &write_chunk(conn, &1))

        if allow_fallback? or served == :requested do

          finish_served(conn, grant, model, selection, served, usage, events)

        else

          finish_pin_violation(grant, model, selection, served, usage)

        end

      {:error, reason} ->

        events = drained_events()

          })

        )

        # The 200 is already on the wire, so the failure travels as terminal

        # frames instead of a status: the same bounded class and upstream

        # status the JSON refusal would have carried, and nothing more.

        write_chunk(conn, data(%{"error" => stream_error(class, status)}))

        write_chunk(conn, "data: [DONE]\n\n")

        finish_provider_error(conn, class, status)

    end

  end

  defp stream_adapter(adapter, request, on_event, options) do

    if Code.ensure_loaded?(adapter) and function_exported?(adapter, :stream, 3) do

      adapter.stream(request, on_event, options)

    else

      adapter.stream(request, on_event)

    end

  end

  defp finish_served(conn, grant, model, selection, served, usage, events) do

    unless Process.get(@state_opened) do

      open_stream(model)

      flush_event_chunks(conn, model, events)

    end

    _ = 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).

    label = model_label(model, served)

    Analytics.capture(

      "inference_model_served",

      analytics_distinct_id(grant),

      Map.merge(selection, %{

        "served_model" => label,

        "served_model_disclosed" => served != :unresolved,

        "outcome" => "served",

        "usage_reported" => usage != %{}

      })

    )

    Enum.each(sse_chunks(events, usage, label), &write_chunk(conn, &1))

    Process.get(@state_conn) || conn

  end

  defp finish_pin_violation(grant, model, selection, served, usage) do

    # Tokens were spent on the model that answered, even though the pin

    # forbids returning that as a successful turn.

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

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

    served_label = model_label(model, served)

    Analytics.capture(

      "inference_model_failed",

      analytics_distinct_id(grant),

      Map.merge(selection, %{

        "outcome" => "model_substituted",

        "reason_code" => "model_substituted",

        "served_model" => served_label,

        "usage_reported" => usage != %{}

      })

    )

    refuse(Process.get(@state_raw_conn), {:model_substituted, model.id, served_label})

  end

  defp finish_provider_error(conn, class, status) do

    if Process.get(@state_opened) do

      # The 200 is already on the wire, so the failure travels as terminal

      # frames instead of a status: the same bounded class and upstream

      # status the JSON refusal would have carried, and nothing more.

      write_chunk(conn, data(%{"error" => stream_error(class, status)}))

      write_chunk(conn, "data: [DONE]\n\n")

      Process.get(@state_conn) || conn

    else

      refuse(

        Process.get(@state_raw_conn) || conn,

        {:provider_failed, class, status}

      )

    end

  end

  defp open_stream(model) do

    if Process.get(@state_opened) do

      :ok

    else

      sent =

        Process.get(@state_raw_conn)

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

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

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

        |> send_chunked(200)

      Process.put(@state_conn, sent)

      Process.put(@state_opened, true)

      :ok

    end

  end

  defp stream_error(class, status) do

    body = %{"code" => "provider_failed", "reason" => class}

    if status == nil, do: body, else: Map.put(body, "upstream_status", status)

  defp emit_event(conn, model, event) do

    record_event(event)

    record_disclosure(event)

    chunks = event_chunks(event)

    if chunks != [] do

      label = chunk_model(model)

    cond do

      Process.get(@state_opened) ->

        write_event_chunks(conn, model, [event])

      pin_confirmed?(model) ->

        open_stream(model)

        write_event_chunks(conn, model, Enum.reverse(Process.get(@state_events) || []))

      true ->

        :ok

    end

    :ok

  end

  defp pin_confirmed?(model) do

    Process.get(@state_allow_fallback) == true or

      served_matches_pin?(model, Process.get(@state_served))

  end

  defp served_matches_pin?(_model, nil), do: false

  defp served_matches_pin?(model, name) when is_binary(name) do

    case Models.fetch(name) do

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

      :error -> name == model.id or name == model.provider_model

    end

  end

  defp write_event_chunks(conn, model, events) do

    label = chunk_model(model)

      Enum.each(chunks, fn payload ->

        write_chunk(conn, data(Map.put(payload, "model", label)))

      end)

    for event <- events, payload <- event_chunks(event) do

      write_chunk(conn, data(Map.put(payload, "model", label)))

    end

    :ok

  end

  defp flush_event_chunks(conn, model, events), do: write_event_chunks(conn, model, events)

  # A fallback disclosure corrects the name on the very chunks that follow it;

  # before one arrives, every chunk names the grant's lane, exactly as the

  # pre-stream header does. METER-001/PROVIDER-002: the response says what

     }}

  end

  # A pin whose provider answered with another model is not a successful turn.

  # The client named one model; attributing a fallback as 200 is the miss #258

  # closes even when PROVIDER-002 would otherwise name the substitute.

  defp error_for({:model_substituted, granted, served}) do

    {502, %{"code" => "model_substituted", "granted" => granted, "served" => served}}

  end

  # The failure class travels with the refusal. `OperationalLog.code/1` takes

  # only the reason's atom tag and bounds it to 64 characters, so it carries no

  # provider text, no prompt, and no credential — it is the same bounded word

                 }

               }

             }

      assert VercelGateway.payload_extra(allow_fallback: true) == VercelGateway.payload_extra()

    end

    test "omits the fallback model list when the grant pinned a model" do

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

      Application.put_env(:openagents, :vercel_gateway_fallback_models, [

        "zai/glm-5.3-flash",

        "zai/glm-5.3",

        "openai/gpt-5.6-luna"

      ])

      on_exit(fn ->

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

      end)

      # Vertex `order` stays; `models` is the instruction to substitute, and a

      # pin must not send it (#258).

      assert VercelGateway.payload_extra(allow_fallback: false) == %{

               providerOptions: %{gateway: %{order: ["vertex"]}}

             }

    end

  end

  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).

  failed primary with `openai/gpt-5.6-luna` and still return 200 — but only

  unnamed-model selection may send that list. A grant that named a model is a

  pin; fallback on that call is a miss even when the substitute is attributed

  honestly (#258). Unnamed selection still reads the serving model back so a

  rescued call is priced against the lane that ran, not the one that was asked

  for (METER-001, PROVIDER-002).

  """

  use OpenAgentsWeb.ConnCase, async: false

    %{grant: grant, token: token}

  end

  # Neither the mint nor the body names a model, so the proxy may still attach

  # the gateway fallback list (#258).

  defp unnamed_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

      })

    %{grant: grant, token: token}

  end

  defp call(conn, token) do

    conn

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

    )

  end

  describe "a pinned grant a fallback model served" do

    test "is not a successful turn", %{conn: conn} do

      # Explore pins `gemini-3.7-flash`. Answering with GLM and calling that

      # 200 is the miss even when the substitute is a catalog model (#258).

      serve_as("zai/glm-5.3-flash")

      %{grant: grant, token: token} = gemini_grant("pinned-glm")

      conn = call(conn, token)

      refute conn.status == 200

      error = Jason.decode!(conn.resp_body)["error"]

      assert error["code"] == "model_substituted"

      assert error["granted"] == @gemini

      assert error["served"] == "glm-5.3-flash"

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

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

    end

  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")

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

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

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

    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")

      %{grant: grant, token: token} = unnamed_grant("attributed")

      conn = call(conn, token)

      # The stream (#263) opens before any provider event, so the header names

      # the lane the call addressed. The disclosure corrects the attribution on

      # the response body itself — every chunk carries the model that answered.

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

      assert get_resp_header(conn, "x-openagents-model") == [grant.model_id]

      chunks =

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

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

      luna = "openai/gpt-5.6-luna"

      serve_as(luna)

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

      {:ok, selected} = Models.fetch(Models.default_id())

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

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

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

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

      end

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

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

      # Nothing is recorded for the lane that actually answered either. It is

      # not a model this deployment admits, so there is no lane to credit.

  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")

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

      conn = call(conn, token)

      assert conn.status == 200

      # correct it with, and naming `unresolved` there would require buffering

      # the whole stream again (#263). The unresolved attribution lives where

      # the record is: the metered usage above.

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

      assert get_resp_header(conn, "x-openagents-model") == [grant.model_id]

    end

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

      disclose_nothing()

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

      %{grant: grant, token: token} = unnamed_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}

      assert Health.status(grant.model_id) == {:unknown, nil}

    end

    test "is not a successful turn when the grant pinned a model", %{conn: conn} do

      disclose_nothing()

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

      conn = call(conn, token)

      refute conn.status == 200

      assert Jason.decode!(conn.resp_body)["error"]["code"] == "model_substituted"

    end

  end