The spending and turn limits of a user (spec §7.3) and who is told when one is near or reached (spec §7.4).

What is counted

• Money — PhoenixKitAgent.Spend: the user's rows of the AI request journal whose metadata.source is "agent", so a call that describes an attachment counts as well as a model call of a turn; every row with a cost, a failed call's included. Micro-dollars, $1 = 1_000_000.
• Turns — the user's user messages with a turn_ref (one per turn), in any of their chats.

The windows are the calendar day and month of the site time zone. The limits in force are PhoenixKitAgent.UserConfig.effective/1's: the user's own, else the module's. A limit of 0 allows nothing.

The money limits apply only on an endpoint whose calls get what they cost in the journal (PhoenixKitAgent.Models.reports_cost?/2: a model call of a turn, or a picture's description on the vision endpoint, where the provider reports a cost or phoenix_kit_ai has a price for the model): on another, nothing would be counted, so only the turn limit applies there — the admin pages say so for the default model. An endpoint that cannot be found keeps the money limits.

When

check/3 runs before a turn, while the turn holds its locks (PhoenixKitAgent.Turns), so the previous turn of the user — and every journal row it wrote — is over by then. A turn that started under its limits runs to its end, even past them.

Notices

Each is sent once per limit and period: a row of phoenix_kit_agent_limit_events (user, kind, period, unique) is inserted first with ON CONFLICT DO NOTHING, and only an insert that went through sends anything.

• 80 % of a limit (check/3) — an in-app notice to the user (PhoenixKit.Notifications.upsert_inapp/3, key agent:limit:<kind>:<period>). Event kind warn_80, period key cost:<period> or turns:<period>, so each of the three limits warns on its own.
• A limit reached (announce_reached/2) — the in-app notice to the user (the same key, so an unread warning becomes the new text), and, only when the user's notify_on_limit is on, a notification of type "agent_limit" to the watchers (create_many/2, which respects a watcher who switched that type off). The two have their own events — the watchers' period key is w:<period>, written only when they are told — so notify_on_limit switched on later in the period still tells the watchers of that period, once.

A call refused by the phoenix_kit_ai budget is signalled by phoenix_kit_ai itself (its limit_reached event, to its watchers and to those of the task, guard_watchers/1); the turn's notice in the chat says the budget is used up.

The watchers are agent_limit_watchers (empty: every Owner) and the user's own notify_user_uuids, without the user, who is told as the user.

Notices name the user by e-mail and the limit with its numbers; nothing of a chat. A notice that cannot be sent is logged as the class of the failure.