AG-UI Protocol Coverage

See how this producer handles each event in the pinned AG-UI 1.0 schema.

After reading this guide, you will know:

• Which event types the gem produces, leaves to the host, or does not emit.
• How success, interruption, cancellation, failure, and reconnect map to events.
• Which protocol gaps the pinned Ruby SDK does not express.

ruby_llm-ag_ui speaks AG-UI 1.0. This page is the audit of what it produces against that schema: every one of the 31 event types the 1.0 Event union defines, with the status this gem gives it and why.

A producer is not required to manufacture events it has no data for. What it must never do is emit an event the schema does not define, or claim a run succeeded when it paused, failed or was cancelled.

The pinned schema

The vendored schema is what the test suite validates against, so a mapping change fails CI rather than a client. RubyLLM::AgUI::Protocol::SCHEMA_COMMIT records the commit, and schema_valid! in the mapper and run specs checks every emitted event against the vendored file.

The 31 event types

Legend:

• produced: emitted from real RubyLLM data on the supported path.
• optional: emitted only when the host opts in and real data exists.
• host-owned: the host owns the payload; this gem does not produce it.
• not produced: the producer has no data for it and never fabricates it.

Produced (13)

Optional (1)

Host-owned, not produced (2)

Not produced (15)

Totals: 13 produced + 1 optional + 2 host-owned + 15 not produced = 31.

Terminal events

One run ends exactly once, and the outcome is part of the run record before it is written:

A paused run is never a success. A cancelled run is never a success. A transport that dies mid-run reports nothing on the wire; the record stays non-terminal and the client can reconnect, and it is never evidence that the work finished.

Reconnect

A client that re-sends the same (threadId, runId) and the same input for a run that already ended gets:

1. RUN_STARTED (with protocolVersion and the input echo),
2. STATE_SNAPSHOT when the run recorded one,
3. the recorded terminal event.

It does not get the run’s text or tool deltas again: replaying them would draw the text twice, and re-running a tool would duplicate the side effect. That is also why MESSAGES_SNAPSHOT is not used because the client’s own conversation is the authority, and the gem will not hand it a second, re-id’d copy.

Where this differs from ag-ui-protocol 0.2.0

The community Ruby SDK (ag-ui-protocol 0.2.0) is what this gem encodes with, so its gaps are visible here. Issue drafts for these SDK gaps are kept under docs/.internal/upstream/ in the repository.

The SDK defines 33 event-type constants; the 1.0 schema defines 31. The two sets differ by exactly the five THINKING_* constants (SDK-only) and the three SUBAGENT_* types (schema-only), and RubyLLM::AgUI::Coverage computes that difference at runtime rather than hardcoding it, so an SDK upgrade that closes a gap shows up as a failing expectation instead of a stale document.

Checking It Yourself

require 'ruby_llm/ag_ui'

RubyLLM::AgUI::Coverage.entries.size # => 31
RubyLLM::AgUI::Coverage.sdk_only_event_types
# => ["THINKING_TEXT_MESSAGE_START", "THINKING_TEXT_MESSAGE_CONTENT", "THINKING_TEXT_MESSAGE_END", "THINKING_START", "THINKING_END"]
RubyLLM::AgUI::Coverage.schema_only_event_types
# => ["SUBAGENT_STARTED", "SUBAGENT_FINISHED", "SUBAGENT_ERROR"]

Every event the mapper and the run emit is validated against the vendored schema in the spec suite (bundle exec rspec), including the negative cases: partial tool arguments, a nil chunk, a tool that raises, and a thinking-only chunk that must produce no event at all.

Next Steps

• Streaming Runs - follow event order and outcomes.
• Compatibility - see what this repository verifies.