`OpenAgentsWeb.InferenceProxyControllerTest`, and

`OpenAgentsWeb.ThreadControllerTest`.

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

Status: Current

Metering that prices some lanes at zero is worse than no metering: it reports a

number, and the number is wrong. `gpt-5.6-luna` is the lane the coder actually

runs on and this deployment has never been given its rates, so a surface that

read a missing cost as zero would have shown `$0.00` beside the account's

largest real spend — in the same typeface as a figure somebody measured.

So every metered usage record says on whose authority it was priced.

`OpenAgents.Inference.Pricing` stamps `pricing_id` on every record

`OpenAgents.Inference.record_usage/2` writes, and the id resolves to one of

three bases:

- `declared` — the operator entered the provider's published rates. This is the

  only basis anything may bill from (`Pricing.billable?/1`).

- `provisional` — the deployment carries rates that were written to make the

  system run, or rates whose table it can no longer dereference. A cost is

  computed and labelled; nothing may bill from it.

- `unpriced` — no rates at all. No `estimated_cost_microusd` is written,

  `Pricing.cost/1` answers `nil`, and no reader substitutes a zero.

Concretely:

- `GET /api/v1/models` publishes `pricing_basis` on every entry beside

  `availability`, so a caller reads what a lane will cost and whether that

  figure can be trusted **before** it spends. An unpriced model publishes no

  `pricing` block at all.

- `OpenAgents.Threads.spend/1` refuses to total a session that touched an

  unpriced lane: `cost.microusd` is `nil`, `cost.unpriced_models` names the

  lanes that made it `nil`, and `cost.priced_microusd` still reports what was

  measured so nothing is discarded. `GET /api/v1/threads/{id}` publishes the

  same shape, nulls included.

- The thread page shows the word `Unpriced` rather than a dollar figure, and

  labels a provisional figure as a working number rather than a bill.

- `OpenAgents.Inference.Credit.spent/1` is a floor, not a total, while

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

  reader shows a balance as whole when it is not.

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.

A `max_cost_microusd` ceiling therefore cannot bound an unpriced grant — it can

only stop spend it can measure — so such a grant is bounded by its call and

token ceilings, by the account's admission cap, and by revocation. Turning an

unpriced lane into a number is an owner action: enter the provider's real rates

in `config :openagents, :model_catalog` and set `source: :declared` in the same

edit. No code here may guess one.

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

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

`OpenAgentsWeb.ModelCatalogControllerTest`,

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

## Durable effects

### EFFECT-001 — An effect commits with the intent that asked for it, and is delivered under lease

| 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` |

| 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` |

  #

  # A model may declare a `pricing` map with `input_per_million_tokens`,

  # `output_per_million_tokens`, and optionally `cached_input_per_million_tokens`.

  # The values below are placeholders that make the existing test suite pass;

  # the operator must replace them with real provider rates before accepting

  # any spend. A model with no `pricing` key records no estimated cost.

  # A pricing map also names itself: `id` is the rate table every usage record

  # priced against it stamps as `pricing_id`, and `source` is where the rates

  # came from — `:declared` for a provider's published rates, anything else

  # (including omitting it) for a working figure. `OpenAgents.Inference.Pricing`

  # reads that word, and only `:declared` is billable (METER-001).

  #

  # Every rate below is a placeholder written to make the system run. None of

  # them was read off a provider's price page, so all of them say `:placeholder`

  # and nothing may bill from a cost they produced. Replacing them is an owner

  # action: enter the provider's real rates and set `source: :declared` in the

  # same edit.

  #

  # A model with no `pricing` key records no estimated cost at all — not a

  # zero. `gpt-5.6-luna` is that model and it is the lane the coder runs on, so

  # the account's metered spend is a floor rather than a total until it has

  # rates. Every read surface says `unpriced` rather than `$0.00`.

  #

  # Gemini 3.7 Flash leads, so it is what a caller that names none gets: fast,

  # a million tokens of context, and steady enough to hold a conversation.

      provider_model: "google/gemini-3.7-flash",

      context_window: 1_048_576,

      max_output: 65_536,

      # Placeholder: the operator must set real provider rates before accepting

      # any spend. The cached-input rate is optional and should be omitted if

      # the provider does not offer one.

      # Placeholder: the operator must set real provider rates and flip `source`

      # to `:declared` before anything bills from this. The cached-input rate is

      # optional and should be omitted if the provider does not offer one.

      pricing: %{

        id: "placeholder.gemini-3.7-flash.v1",

        source: :placeholder,

        input_per_million_tokens: 1_250_000,

        output_per_million_tokens: 10_000_000,

        cached_input_per_million_tokens: 100_000

      # with a real task spent the whole budget reasoning and returned an empty

      # 200 after three minutes, which read as the proxy having failed.

      max_output: 64_000,

      # Placeholder: the operator must set real provider rates before accepting

      # any spend. This entry does not declare a cached-input rate.

      # Placeholder: the operator must set real provider rates and flip `source`

      # to `:declared` before anything bills from this. This entry does not

      # declare a cached-input rate.

      pricing: %{

        id: "placeholder.ox-alpha.v1",

        source: :placeholder,

        input_per_million_tokens: 500_000,

        output_per_million_tokens: 2_000_000

      }

      context_window: 272_000,

      max_output: 4_096

      # This entry deliberately omits `pricing`, so a grant pinned to it records

      # no estimated cost rather than a made-up zero.

      # no estimated cost rather than a made-up zero. Its usage records stamp

      # `pricing_id: "unpriced"`, `Threads.spend/1` refuses to total a session

      # that touched it, and the thread page shows the word instead of a

      # figure. Giving this lane real rates is the single highest-value edit in

      # this file: it is where the coder's spend actually goes.

    }

  ],

  gemini_api_key: nil,

generation-fenced and revocable, and has call, token, and cost ceilings. It is

not an OpenAI credential and cannot select a model outside the grant.

A cost ceiling only bounds spend the deployment can price. Read

`pricing_basis` on each entry of `GET /api/v1/models` before you spend:

`declared` is billable, `provisional` is a working figure, and `unpriced`

means no cost is reported for that lane at all. On a thread,

`spend.cost.microusd` and `grant.remaining.cost_microusd` are `null` whenever

an unpriced lane contributed, and `spend.cost.unpriced_models` names the lanes

that made them null. A client must handle the `null` rather than render a zero

it was never given (METER-001).

`OpenAgentsWeb.RouteAuthority.inventory/0` is the executable inventory for

HTTP routes and endpoint sockets. The test gate fails when a new route does not

resolve to one of the admitted authority classes with a principal and scope.

the conversation is still to come; see the audit in

`docs/2026-08-23-thread-primitive-audit.md`.

**Pricing basis** — one word saying whether a reported cost can be trusted, on

every catalog entry and every metered usage record (METER-001). `declared`

means the operator entered the provider's published rates and the figure is

billable. `provisional` means the deployment carries rates that were written to

make the system run, or rates whose table it can no longer dereference; the

figure is a working number and nothing bills from it. `unpriced` means there

are no rates at all. The authority is `OpenAgents.Inference.Pricing`, and every

record names its rate table in `pricing_id`.

**Unpriced** — the deployment does not know what a call cost. It is not the

same word as free, and it is never rendered as `$0.00`: an unpriced record

carries no `estimated_cost_microusd`, `OpenAgents.Threads.spend/1` reports a

null total and names the lanes that made it null, and the thread page shows the

word. `gpt-5.6-luna` is unpriced today, which is why the distinction is load

bearing rather than pedantic — it is the lane the coder runs on. Giving a lane

rates is an owner action, never an inference.

**Thread transcript** — the prompts, responses, tool activity, code changes,

and metadata that explain what happened in a thread. Authoritative copies live

in PostgreSQL (messages, tool steps, receipts), not on a Git branch. The

  """

  import Ecto.Query

  alias OpenAgents.Inference.{Grant, Models}

  alias OpenAgents.Inference.{Grant, Models, Pricing}

  alias OpenAgents.Machines.Machine

  alias OpenAgents.Repo

  # ── budget ──────────────────────────────────────────────────────────────

  # A cost ceiling can only stop spend it can measure. An unpriced model writes

  # no `estimated_cost_microusd`, so `max_cost_microusd` never fires for it and

  # such a grant is bounded by its call and token ceilings, by the account's

  # admission cap, and by revocation — not by money. That is a consequence of

  # not knowing the rates rather than a decision to let the lane run free, and

  # it is why `Threads.spend/1` and `Credit.unpriced_calls/1` publish the

  # unpriced calls instead of folding them into a total (METER-001).

  @doc false

  def over_budget?(%Grant{} = grant) do

    tokens = integer(grant.usage["total_tokens"])

    merged

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

    |> put_cost(model_id)

    |> Pricing.price(model_id)

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

  end

    end

  end

  defp put_cost(merged, model_id) do

    case Models.fetch(model_id) do

      {:ok, %{pricing: %{input_per_million_tokens: i, output_per_million_tokens: o} = pricing}} ->

        input = integer(merged["input_tokens"])

        output = integer(merged["output_tokens"])

        cache_read = integer(merged["cache_read_input_tokens"])

        cache_write = integer(merged["cache_write_input_tokens"])

        cached_rate = Map.get(pricing, :cached_input_per_million_tokens, i)

        # Cached read tokens are split from the rest of the input and priced at

        # the cached rate where one is declared. Cache write tokens are charged

        # as regular input because they are not a cached read.

        uncached = max(0, input - cache_read) + cache_write

        cost =

          uncached * i + cache_read * cached_rate + output * o

        Map.put(merged, "estimated_cost_microusd", div(cost, 1_000_000))

      _ ->

        merged

    end

  end

  defp normalize_usage(usage) do

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

      case raw_value(usage, field) do

  alias OpenAgents.Conversations.Visitor

  alias OpenAgents.Inference.Grant

  alias OpenAgents.Inference.Pricing

  alias OpenAgents.Repo

  @doc """

  @spec visitor_allowance() :: non_neg_integer()

  def visitor_allowance, do: setting(:visitor_credit_microusd, 2_000_000)

  @doc "What every grant this account has held has metered, in microUSD."

  @doc """

  What every grant this account has held has metered, in microUSD.

  Only priced calls contribute, so this is a floor rather than a total whenever

  `unpriced_calls/1` is above zero. It stays a bare integer because the grant

  ceiling has to be a number — a ceiling of `nil` would admit unbounded

  spend — and the reader that wants the honest picture asks `balance/1`.

  """

  @spec spent(String.t()) :: non_neg_integer()

  def spent(visitor_id) when is_binary(visitor_id) do

    Repo.one(

    )

  end

  @doc "What is left of this account's credit, in microUSD. Never negative."

  @doc """

  What is left of this account's credit, in microUSD. Never negative.

  This is a ceiling rather than a balance, and the difference matters while any

  lane is unpriced. A call on a model with no declared rates writes no cost, so

  it draws nothing down here: the remainder is what the account may still be

  *ceiled* at, not what it has left to spend in the world. `unpriced_calls/1`

  is how much of the account's real spend this figure cannot see (METER-001).

  """

  @spec remaining(String.t()) :: non_neg_integer()

  def remaining(visitor_id) when is_binary(visitor_id) do

    max(allowance(visitor_id) - spent(visitor_id), 0)

  end

  @doc """

  How many of this account's metered calls carry no price.

  `spent/1` is a floor while this is above zero, and saying so is the whole

  reason this function exists. A surface that showed a balance without it would

  be reporting an account as barely touched while its coder ran all day on a

  lane nobody entered rates for.

  """

  @spec unpriced_calls(String.t()) :: non_neg_integer()

  def unpriced_calls(visitor_id) when is_binary(visitor_id) do

    Repo.all(

      from grant in Grant,

        where: grant.owner_visitor_id == ^visitor_id and grant.call_count > 0,

        select: {grant.model_id, grant.usage, grant.call_count}

    )

    |> Enum.filter(fn {_model, usage, _calls} ->

      Pricing.usage_basis(usage) == Pricing.unpriced()

    end)

    |> Enum.map(fn {_model, _usage, calls} -> calls end)

    |> Enum.sum()

  end

  @doc """

  The account's credit as one readable fact, including what it cannot see.

  `complete?` is false whenever an unpriced call has been metered, which is the

  signal a caller needs before it renders `spent_microusd` as though it were

  the account's whole spend.

  """

  @spec balance(String.t()) :: %{

          allowance_microusd: non_neg_integer(),

          spent_microusd: non_neg_integer(),

          remaining_microusd: non_neg_integer(),

          unpriced_calls: non_neg_integer(),

          complete?: boolean()

        }

  def balance(visitor_id) when is_binary(visitor_id) do

    unpriced = unpriced_calls(visitor_id)

    %{

      allowance_microusd: allowance(visitor_id),

      spent_microusd: spent(visitor_id),

      remaining_microusd: remaining(visitor_id),

      unpriced_calls: unpriced,

      complete?: unpriced == 0

    }

  end

  defp signed_in?(visitor_id) do

    Repo.exists?(from v in Visitor, where: v.id == ^visitor_id and not is_nil(v.user_id))

  end

defmodule OpenAgents.Inference.Models do

  alias OpenAgents.Inference.Health

  alias OpenAgents.Inference.Pricing

  @moduledoc """

  The typed model catalog: every model this deployment serves, and the

  about how the server is wired. Pricing is exposed only when the deployment

  has declared rates for a model; an unpriced model has no `pricing` key so it

  is not read as zero before spend.

  Absence is a weak signal, though — a client that forgets to check for the key

  reads a missing price as no price rather than as an unknown one. So every

  entry also carries `pricing_basis`, one word alongside `availability`:

  `declared` where the operator entered the provider's published rates,

  `provisional` where the rates are a working figure nothing may bill from, and

  `unpriced` where there are none. A caller can read what a lane will cost, and

  whether that figure can be trusted, before it spends anything (METER-001).

  """

  @spec catalog() :: [map()]

  def catalog do

        "context_window" => model.context_window,

        "max_output" => model.max_output,

        "availability" => availability(model),

        "pricing_basis" => Pricing.basis_of(model.pricing),

        "default" => model.id == default_id

      }

  defp public_pricing(pricing) do

    base = %{

      "id" => Pricing.pricing_id(pricing),

      "basis" => Pricing.basis_of(pricing),

      "input_per_million_tokens" => pricing.input_per_million_tokens,

      "output_per_million_tokens" => pricing.output_per_million_tokens

    }

defmodule OpenAgents.Inference.Pricing do

  @moduledoc """

  What a metered call cost, and on whose authority.

  Metering that prices some lanes at zero is worse than no metering: it reports

  a number, and the number is wrong. `gpt-5.6-luna` is the lane the coder

  actually runs on and this deployment has never been told its rates, so a

  surface that read a missing cost as zero would have shown `$0.00` beside a

  session that spent real money — and shown it in the same typeface as a figure

  that was measured.

  So a cost is never a bare integer here. Every metered usage record carries a

  `pricing_id` naming the rate table it was priced against, and the id resolves

  to one of three bases:

    * `declared` — the operator entered the provider's published rates. This is

      the only basis anything may bill from (`billable?/1`).

    * `provisional` — the deployment carries rates that were written to make

      the system run rather than read off a provider's price page, or rates

      whose table is unnamed. A cost is computed and labelled; no bill may

      derive from it.

    * `unpriced` — no rates at all. No `estimated_cost_microusd` is written,

      `cost/1` answers `nil`, and every reader shows the word rather than a

      zero.

  `unpriced` is not an error state and it is not a free lane. 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 all the

  way to the read surfaces. Turning it into a number is an owner action —

  entering real rates in `config :openagents, :model_catalog` — not something

  this module may guess at.

  The `pricing_id` convention is `OpenAgents.Voice.Usage`'s, so

  `OpenAgents.DataRights.AtifExport` reads inference usage and voice usage with

  the same rule. The one difference is deliberate: voice writes a zero cost

  beside `pricing_id: "unpriced"`, and inference writes no cost key at all.

  """

  alias OpenAgents.Inference.Models

  @unpriced "unpriced"

  @unattributed "unattributed"

  @doc "The `pricing_id` written for a lane with no declared rates."

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

  def unpriced, do: @unpriced

  @doc """

  The basis of a catalog pricing map: `declared`, `provisional`, or `unpriced`.

  A pricing map that does not say where its rates came from is `provisional`,

  not `declared`. Failing closed is the point: a rate somebody added without

  recording its source is exactly the rate nothing should bill from.

  """

  @spec basis_of(map() | nil) :: String.t()

  def basis_of(nil), do: @unpriced

  def basis_of(%{source: :declared}), do: "declared"

  def basis_of(%{}), do: "provisional"

  @doc "The basis for a model, by catalog id or resolved model."

  @spec basis(map() | String.t() | nil) :: String.t()

  def basis(%{pricing: pricing}), do: basis_of(pricing)

  def basis(model_id) do

    case Models.fetch(model_id) do

      {:ok, model} -> basis_of(model.pricing)

      :error -> @unpriced

    end

  end

  @doc """

  The id of the rate table a model is priced against.

  `unpriced` where the catalog declares no rates, `unattributed` where it

  declares rates without naming their table.

  """

  @spec pricing_id(map() | nil) :: String.t()

  def pricing_id(nil), do: @unpriced

  def pricing_id(%{} = pricing), do: Map.get(pricing, :id) || @unattributed

  @doc "The id of the rate table this model is priced against, by catalog id."

  @spec pricing_id_for(String.t() | nil) :: String.t()

  def pricing_id_for(model_id) do

    case Models.fetch(model_id) do

      {:ok, model} -> pricing_id(model.pricing)

      :error -> @unpriced

    end

  end

  @doc """

  Price a merged usage map against a model's declared rates.

  Always stamps `pricing_id`, so the stored record says on whose authority it

  was priced — or that it was not priced at all. `estimated_cost_microusd` is

  written only where rates exist, because a zero there would be read as a

  measurement.

  Cached read tokens are split out of the input and charged at the cached rate

  where the model declares one. Cache write tokens are charged as regular

  input, because writing a cache is not reading one.

  """

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

  def price(usage, model_id) when is_map(usage) do

    pricing =

      case Models.fetch(model_id) do

        {:ok, model} -> model.pricing

        :error -> nil

      end

    usage

    |> Map.put("pricing_id", pricing_id(pricing))

    |> put_cost(pricing)

  end

  defp put_cost(

         usage,

         %{input_per_million_tokens: input_rate, output_per_million_tokens: out_rate} = pricing

       ) do

    input = integer(usage["input_tokens"])

    output = integer(usage["output_tokens"])

    cache_read = integer(usage["cache_read_input_tokens"])

    cache_write = integer(usage["cache_write_input_tokens"])

    cached_rate = Map.get(pricing, :cached_input_per_million_tokens, input_rate)

    uncached = max(0, input - cache_read) + cache_write

    cost = uncached * input_rate + cache_read * cached_rate + output * out_rate

    Map.put(usage, "estimated_cost_microusd", div(cost, 1_000_000))

  end

  defp put_cost(usage, _no_rates), do: usage

  @doc """

  What a stored usage record cost, or `nil` where the deployment does not know.

  `nil` is the whole point of this function. Callers that need a number must

  decide what to do without one instead of being handed a zero that reads like

  a measurement.

  """

  @spec cost(map() | nil) :: integer() | nil

  def cost(%{} = usage) do

    case Map.get(usage, "estimated_cost_microusd") do

      value when is_integer(value) -> value

      value when is_float(value) -> trunc(value)

      _absent -> nil

    end

  end

  def cost(_usage), do: nil

  @doc """

  The basis of a stored usage record.

  A record written before `pricing_id` existed carries a cost and no table

  name. That is `provisional` — a figure whose rates cannot be dereferenced is

  precisely a figure nothing may bill from — and a record with neither is

  `unpriced`.

  """

  @spec usage_basis(map() | nil) :: String.t()

  def usage_basis(%{} = usage) do

    case Map.get(usage, "pricing_id") do

      @unpriced -> @unpriced

      id when is_binary(id) -> basis_of_id(id, usage)

      _absent -> if is_nil(cost(usage)), do: @unpriced, else: "provisional"

    end

  end

  def usage_basis(_usage), do: @unpriced

  defp basis_of_id(id, usage) do

    cond do

      is_nil(cost(usage)) -> @unpriced

      declared_id?(id) -> "declared"

      true -> "provisional"

    end

  end

  # A stored record names its table, and whether that table was declared is a

  # property of the catalog rather than of the string. A table that has since

  # been removed from the catalog is read as provisional: it was priced against

  # something this deployment can no longer dereference, and NO BILL WITHOUT A

  # DEREFERENCEABLE USAGE RECORD is the contract.

  defp declared_id?(id) do

    Enum.any?(Models.all(), fn model ->

      pricing_id(model.pricing) == id and basis_of(model.pricing) == "declared"

    end)

  end

  @doc """

  Whether a stored usage record may be billed from.

  Only a `declared` basis qualifies. A provisional cost is a working figure and

  an unpriced call is an unknown; billing from either is the failure this

  module exists to prevent.

  """

  @spec billable?(map() | nil) :: boolean()

  def billable?(usage), do: usage_basis(usage) == "declared"

  @doc "Whether this record carries a cost at all."

  @spec priced?(map() | nil) :: boolean()

  def priced?(usage), do: not is_nil(cost(usage))

  defp integer(value) when is_integer(value), do: value

  defp integer(value) when is_float(value), do: trunc(value)

  defp integer(_value), do: 0

end

  alias OpenAgents.Conversations

  alias OpenAgents.Conversations.Visitor

  alias OpenAgents.Inference

  alias OpenAgents.Inference.{Credit, Grant, Models}

  alias OpenAgents.Inference.{Credit, Grant, Models, Pricing}

  alias OpenAgents.Issues.Issue

  alias OpenAgents.Repo

  alias OpenAgents.Threads.Event

  Absent stays absent. A dimension no provider reported is not summed into

  existence as a zero, because a zero reads as a measurement and this is the

  absence of one (#220).

  `:cost` is the same rule applied to money, and it is stricter than the sum in

  `:usage` because money is what somebody eventually pays. A session that

  touched a lane this deployment has no rates for cannot be totalled honestly,

  so `cost.microusd` is `nil` and `cost.unpriced_models` names the lanes that

  made it `nil`. What was priced is still reported, as `cost.priced_microusd`,

  so nothing is thrown away — but a reader that wants "the cost" has to notice

  it does not have one (METER-001).

  """

  @spec spend(Thread.t() | String.t()) :: %{

          calls: non_neg_integer(),

          grants: non_neg_integer(),

          usage: map()

          usage: map(),

          cost: %{

            microusd: non_neg_integer() | nil,

            priced_microusd: non_neg_integer(),

            basis: String.t(),

            unpriced_calls: non_neg_integer(),

            unpriced_models: [String.t()]

          }

        }

  def spend(%Thread{id: thread_id}), do: spend(thread_id)

    grants =

      from(grant in Grant,

        where: grant.thread_id == ^thread_id,

        select: {grant.call_count, grant.usage}

        select: {grant.call_count, grant.usage, grant.model_id}

      )

      |> Repo.all()

    usage =

      Enum.reduce(grants, %{}, fn {_calls, usage}, acc ->

      Enum.reduce(grants, %{}, fn {_calls, usage, _model}, acc ->

        Enum.reduce(usage || %{}, acc, fn

          {key, value}, inner when is_integer(value) ->

            Map.update(inner, key, value, &(&1 + value))

      end)

    %{

      calls: Enum.sum(Enum.map(grants, fn {calls, _usage} -> calls || 0 end)),

      calls: Enum.sum(Enum.map(grants, fn {calls, _usage, _model} -> calls || 0 end)),

      grants: length(grants),

      usage: usage

      usage: usage,

      cost: cost_view(grants)

    }

  end

  # One grant contributes to the cost only if it bought something. A grant that

  # was minted and never called says nothing about pricing either way, so an

  # unpriced grant with no calls does not make a session's total unknown.

  defp cost_view(grants) do

    metered = Enum.filter(grants, fn {calls, _usage, _model} -> (calls || 0) > 0 end)

    priced_microusd =

      metered

      |> Enum.map(fn {_calls, usage, _model} -> Pricing.cost(usage) || 0 end)

      |> Enum.sum()

    unpriced =

      Enum.filter(metered, fn {_calls, usage, _model} ->

        Pricing.usage_basis(usage) == Pricing.unpriced()

      end)

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

    unpriced_models =

      unpriced

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

      |> Enum.reject(&is_nil/1)

      |> Enum.uniq()

      |> Enum.sort()

    bases =

      metered

      |> Enum.map(fn {_calls, usage, _model} -> Pricing.usage_basis(usage) end)

      |> Enum.uniq()

    %{

      microusd: if(unpriced == [] and metered != [], do: priced_microusd),

      priced_microusd: priced_microusd,

      basis: basis_word(metered, bases, unpriced),

      unpriced_calls: unpriced_calls,

      unpriced_models: unpriced_models

    }

  end

  # `absent` is not `unpriced`: nothing was bought, so there is nothing to

  # price. `unpriced` wins over the rest because it is the one word that says

  # the figure beside it is incomplete, and `provisional` wins over `declared`

  # because a total is only as billable as its least trustworthy part.

  defp basis_word([], _bases, _unpriced), do: "absent"

  defp basis_word(_metered, _bases, [_ | _]), do: "unpriced"

  defp basis_word(_metered, bases, []) do

    if "provisional" in bases, do: "provisional", else: "declared"

  end

  @doc "How many threads one account may hold open at once, or `nil` for no limit."

  @spec maximum_open_per_account() :: pos_integer() | nil

  def maximum_open_per_account, do: setting(:maximum_open_threads_per_account, nil)

          "anonymous visitor against `visitor_microusd`, for the life of the " <>

          "account rather than per thread. A thread's grant is minted for the " <>

          "remainder, so `grant.max_cost_microusd` in the mint response is " <>

          "what is left rather than a fixed cap."

          "what is left rather than a fixed cap.",

      "unpriced_lanes" =>

        "A model this deployment has declared no rates for records no cost, " <>

          "so its calls draw nothing down and its spend is reported as " <>

          "unknown rather than as zero. Read `pricing_basis` on each entry of " <>

          "`GET /api/v1/models` before you spend: `declared` is billable, " <>

          "`provisional` is a working figure, and `unpriced` means a cost " <>

          "will not be reported at all. On a thread, `spend.cost.microusd` is " <>

          "null whenever `spend.cost.unpriced_models` is non-empty."

    }

  end

  alias OpenAgents.Conversations

  alias OpenAgents.Inference

  alias OpenAgents.Inference.{Credit, Grant, Models}

  alias OpenAgents.Inference.{Credit, Grant, Models, Pricing}

  alias OpenAgents.Threads

  alias OpenAgents.Threads.Thread

  alias OpenAgentsWeb.ApiError

  defp spend_view(%Thread{} = thread) do

    spend = Threads.spend(thread)

    %{"calls" => spend.calls, "grants" => spend.grants, "usage" => spend.usage}

    %{

      "calls" => spend.calls,

      "grants" => spend.grants,

      "usage" => spend.usage,

      # `cost.microusd` is null when any lane this session used has no declared

      # rates. A client that renders it as a currency has to handle the null

      # rather than print a zero it was never given (METER-001).

      "cost" => %{

        "microusd" => spend.cost.microusd,

        "priced_microusd" => spend.cost.priced_microusd,

        "basis" => spend.cost.basis,

        "unpriced_calls" => spend.cost.unpriced_calls,

        "unpriced_models" => spend.cost.unpriced_models

      }

    }

  end

  # The plaintext token exists exactly once, here. Everything else in this map

      "call_count" => grant.call_count,

      "usage" => grant.usage,

      "limits" => limits(grant),

      # What this grant was priced against, so the figures below can be

      # dereferenced rather than trusted. `unpriced` means the deployment has

      # no rates for this model: `spent_cost_microusd` is null, the cost

      # remainder is null, and neither is a zero (METER-001).

      "pricing" => %{

        "id" => Pricing.pricing_id_for(grant.model_id),

        "basis" => Pricing.basis(grant.model_id),

        "billable" => Pricing.billable?(grant.usage)

      },

      "spent" => %{

        "calls" => grant.call_count,

        "total_tokens" => spent(grant, "total_tokens"),

        "cost_microusd" => Pricing.cost(grant.usage)

      },

      "remaining" => %{

        "calls" => remaining(grant.max_calls, grant.call_count),

        "total_tokens" => remaining(grant.max_total_tokens, spent(grant, "total_tokens")),

        "cost_microusd" =>

          remaining(grant.max_cost_microusd, spent(grant, "estimated_cost_microusd"))

        # An unpriced grant has no cost remainder to report. Subtracting a zero

        # from the ceiling would publish the whole ceiling as headroom on a

        # grant that has been spending all along.

        "cost_microusd" => cost_remaining(grant)

      }

    }

  end

  defp cost_remaining(%Grant{} = grant) do

    case Pricing.cost(grant.usage) do

      nil -> nil

      cost -> remaining(grant.max_cost_microusd, cost)

    end

  end

  defp limits(%Grant{} = grant) do

    %{

      "max_calls" => grant.max_calls,

  use OpenAgentsWeb, :live_view

  alias OpenAgents.Inference.Pricing

  alias OpenAgents.Markdown

  alias OpenAgents.Threads

            </div>

            <div>

              <div class="text-xs text-muted-foreground">Calls</div>

              <div class="tabular-nums">{@grant.call_count} / {@grant.max_calls}</div>

              <div class="tabular-nums">{@grant.call_count} / {ceiling(@grant.max_calls)}</div>

            </div>

            <div>

              <div class="text-xs text-muted-foreground">Tokens</div>

              <div class="tabular-nums">

                {grant_spent(@grant, "total_tokens")} / {@grant.max_total_tokens}

                {grant_spent(@grant, "total_tokens")} / {ceiling(@grant.max_total_tokens)}

              </div>

            </div>

            <div>

              <div class="text-xs text-muted-foreground">Cost</div>

              <div class="tabular-nums">

                {dollars(grant_spent(@grant, "estimated_cost_microusd"))} / {dollars(

                  @grant.max_cost_microusd

                )}

              <div id="thread-budget-cost" class="tabular-nums" data-basis={cost_basis(@grant)}>

                {cost_spent(@grant)} / {dollars(@grant.max_cost_microusd)}

              </div>

              <div

                :if={cost_basis(@grant) != "declared"}

                id="thread-budget-cost-note"

                class="text-xs text-muted-foreground"

              >

                {cost_note(cost_basis(@grant))}

              </div>

            </div>

            <div :if={@grant.expires_at}>

    end

  end

  # A null ceiling is unbounded, not zero and not missing. Rendering nil left

  # the denominator blank, which read as a rendering fault rather than as the

  # thread's actual authority.

  defp ceiling(nil), do: "∞"

  defp ceiling(value), do: value

  defp dollars(nil), do: "∞"

  defp dollars(microusd), do: "$#{:erlang.float_to_binary(microusd / 1_000_000, decimals: 2)}"

  # What this grant has spent, or the word for not knowing. `$0.00` is what

  # this cell used to show for a lane with no declared rates, and it was the

  # most confident wrong number on the page: the coder runs on that lane

  # (METER-001).

  defp cost_spent(grant) do

    case Pricing.cost(grant.usage) do

      nil -> "Unpriced"

      microusd -> dollars(microusd)

    end

  end

  defp cost_basis(grant), do: Pricing.usage_basis(grant.usage)

  defp cost_note("unpriced"),

    do: "No rates declared for this model, so this session's cost is unknown rather than zero."

  defp cost_note(_provisional),

    do: "Provisional rates. This is a working figure, not a bill."

  # The tier word plus what it means for a reader, because "dark" alone tells

  # the owner nothing about who can see the page they are looking at.

  defp visibility_label("dark"), do: "dark · only you"

    assert Threads.ceilings(visitor_id) == {:error, :credit_exhausted}

  end

  # METER-001. A cost ceiling can only stop spend it can measure, so a lane

  # with no declared rates draws nothing down. That is a consequence of not

  # knowing the rates, and the account's read has to say so rather than report

  # a balance that looks untouched.

  describe "spend the deployment has no price for" do

    test "an unpriced call draws nothing down, and the balance says so" do

      owner = account("credit-unpriced")

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

      {:ok, thread} = Threads.open(%Visitor{id: owner.id}, "Run the unpriced lane", model: luna)

      {:ok, _fenced, grant, _token} = Threads.mint_grant(thread)

      {:ok, _metered} = Inference.record_usage(grant, %{"output_tokens" => 500_000})

      # `spent/1` is a floor, not a total, and the floor here is zero.

      assert Credit.spent(owner.id) == 0

      assert Credit.remaining(owner.id) == Credit.allowance(owner.id)

      # What stops that reading as "this account has spent nothing".

      assert Credit.unpriced_calls(owner.id) == 1

      balance = Credit.balance(owner.id)

      assert balance.spent_microusd == 0

      assert balance.unpriced_calls == 1

      refute balance.complete?

    end

    test "an account whose every call was priced reports a complete balance" do

      owner = account("credit-complete")

      {:ok, _metered} =

        Inference.record_usage(minted(owner.id), %{

          "output_tokens" => output_tokens_costing(100_000)

        })

      balance = Credit.balance(owner.id)

      assert balance.spent_microusd == 100_000

      assert balance.unpriced_calls == 0

      assert balance.complete?

    end

    test "a grant that never bought anything is not counted as unpriced spend" do

      owner = account("credit-idle")

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

      {:ok, thread} = Threads.open(%Visitor{id: owner.id}, "Mint and stop", model: luna)

      {:ok, _fenced, _grant, _token} = Threads.mint_grant(thread)

      assert Credit.unpriced_calls(owner.id) == 0

      assert Credit.balance(owner.id).complete?

    end

  end

end

defmodule OpenAgents.Inference.PricingTest do

  @moduledoc """

  The rule that a cost is reported only where a price exists (METER-001).

  The failure this guards against is not a crash. It is a number: a lane with

  no declared rates summing to `$0.00` on a surface that looks like a bill,

  in the same typeface as a figure somebody measured. `gpt-5.6-luna` is that

  lane and it is the one the coder runs on, so every assertion below about

  "unpriced" is an assertion about the deployment's largest real spend.

  """

  use ExUnit.Case, async: true

  alias OpenAgents.Inference.Pricing

  defp unpriced_model_id, do: Application.fetch_env!(:openagents, :openai_model)

  describe "the basis of a catalog pricing map" do

    test "no pricing map at all is unpriced" do

      assert Pricing.basis_of(nil) == "unpriced"

    end

    test "rates that name the provider as their source are declared" do

      assert Pricing.basis_of(%{source: :declared, input_per_million_tokens: 1}) == "declared"

    end

    test "rates that do not say where they came from are provisional, not declared" do

      assert Pricing.basis_of(%{input_per_million_tokens: 1}) == "provisional"

      assert Pricing.basis_of(%{source: :placeholder, input_per_million_tokens: 1}) ==

               "provisional"

    end

  end

  describe "the id of the rate table" do

    test "a lane with no rates is priced against the unpriced table" do

      assert Pricing.pricing_id(nil) == "unpriced"

      assert Pricing.pricing_id_for(unpriced_model_id()) == "unpriced"

    end

    test "a lane with rates publishes the table those rates came from" do

      assert Pricing.pricing_id_for("gemini-3.7-flash") == "placeholder.gemini-3.7-flash.v1"

    end

    test "rates without a table name are unattributed rather than silently accepted" do

      assert Pricing.pricing_id(%{input_per_million_tokens: 1}) == "unattributed"

    end

    test "a model outside the catalog is unpriced rather than assumed free" do

      assert Pricing.pricing_id_for("not-a-model-this-deployment-serves") == "unpriced"

      assert Pricing.basis("not-a-model-this-deployment-serves") == "unpriced"

    end

  end

  describe "pricing one usage record" do

    test "an unpriced model writes no cost key — not a zero" do