## Summary The AI gateway now emits a terminal `usage` event on `/v2/chat/agent` carrying per-model token counts, merged in [ai-assist!6185](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/6185). GitLab Rails has no matching event class, so `Gitlab::Duo::Chat::AgentEventParser` cannot resolve it and logs `Failed to find the event class in GitLab-Rails.` on every Duo Chat request. Chat itself is unaffected: the parser returns `nil` and the executors ignore the event. @alejandro [flagged this as acceptable when merging](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/6185#note_3608005668) and named this file location as the follow-up. This issue is that follow-up. ## Current behaviour Every Duo Chat request against an instance whose AI gateway includes ai-assist!6185 logs, once per request: ``` Failed to find the event class in GitLab-Rails. event_type=usage event_name=parsing_error ai_component=duo_chat ``` Responses themselves are correct. `AgentEventParser#parse` rescues the `NameError`, returns `nil`, and `StepExecutor#step` drops the event at `next unless event`. ## Expected behaviour `usage` parses into a first-class event, nothing is logged as an error, and the per-model token counts it carries are reachable from the parsed object. ## There are two regression traps here Adding the event class on its own is **not** safe, and neither failure would be loud. Until now every event that reached the `events` array was part of the answer. `usage` is the first that is not, and it is terminal, so it arrives last. Two consumers read the array as a whole. **1. The streaming cut-off warning.** `StepExecutor#add_cut_off_warning_event_if_response_cut_off` reads `events.last` **twice**, and `final_answer_streaming_cut_off?` bails on `return false unless event.instance_of?(AgentEvents::FinalAnswerDelta)`. With `usage` last the guard never matches, so the truncation warning stops firing for every cut-off response with nothing logged. That warning is user-facing and sits behind the `duo_non_agentic_chat_ai_message_cut_off_warning` flag, which makes it easy to miss in review. **2. The empty-stream check.** `ReactExecutor#execute` raises `EmptyEventsError` when the array is empty, which surfaces as error `A1002` after a single request. A stream carrying only `usage` is no longer empty, so it passes that check, all three processors return `nil`, and `next unless answer` sends the identical request again, up to `MAX_ITERATIONS` (10) times, before failing with `ExhaustedLoopError` and a misleading "reached the limit" message. Up to ten times the token cost and latency for a case that used to fail immediately. ## Proposed change **1. Add `ee/lib/gitlab/duo/chat/agent_events/usage.rb`:** ```ruby class Usage < BaseEvent # { "<model>" => { "input_tokens" => N, "output_tokens" => M } } # Per model rather than summed, because token counts are not equivalent across models. def usage data["usage"] end def metadata? true end end ``` **2. Mark metadata on the base class**, so both consumers share one predicate instead of repeating a class check. `BaseEvent#metadata?` returns `false`. **3. Exclude metadata at both reads in `StepExecutor#add_cut_off_warning_event_if_response_cut_off`:** ```ruby answer_events = events.reject(&:metadata?) return unless final_answer_streaming_cut_off?(answer_events.last) ``` and later in the same method: ```ruby warning_text = cut_off_warning_for(answer_events.last) ``` The method reads `events.last` twice. Filtering only the guard leaves `cut_off_warning_for(events.last)` receiving the `usage` event, which has no `finish_reason`, so it raises `NoMethodError` exactly when the warning should fire. **4. Treat an all-metadata array as empty in `ReactExecutor#execute`:** ```ruby raise EmptyEventsError if events.all?(&:metadata?) ``` `all?` is correct on the empty array, so the existing empty-stream behaviour is unchanged. `reject` rather than searching backwards for the last `FinalAnswerDelta`: the latter reads better but changes behaviour in an unrelated case, since a stream ending in an `Error` produces no warning today and would begin producing one. `reject` is exactly behaviour-preserving for every stream that carries no metadata event. ## Acceptance criteria - [ ] `usage` resolves to `Gitlab::Duo::Chat::AgentEvents::Usage` and no longer logs a parsing error - [ ] A spec asserts the cut-off warning still fires when a `usage` event trails a truncated `final_answer_delta` - [ ] A spec asserts a usage-only stream still raises `EmptyEventsError` rather than entering the retry loop - [ ] Per-model token counts are reachable from the parsed event ## Why this matters beyond the log noise `usage` carries the per-request, per-model token count. Having it available in Rails is the prerequisite for storing it on `Ai::UsageEvent#extras`, which is what self-managed and air-gapped instances need for per-user token attribution without querying the database directly. Context in #466072. ## References - [ai-assist!6185](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/6185) emits the event (merged 2026-07-27) - [ai-assist#2535](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/work_items/2535) the originating feature request (closed by the above) - Event shape: `{"type": "usage", "data": {"usage": {"<model>": {"input_tokens": 8, "output_tokens": 12}}}}` - AIGW defines five agent event types (`action`, `final_answer_delta`, `unknown`, `error`, `usage`) in `ai_gateway/chat/agents/typing.py`; `usage` is the only one Rails lacks a class for