ruby_llm-ag_ui 0.1.0

data/docs/_getting_started/overview.md

@@ -0,0 +1,189 @@
+---
+layout: default
+title: "How RubyLLM AG-UI Works"
+nav_order: 2
+description: One RubyLLM chat turn becomes one ordered AG-UI run with a single recorded outcome.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* Which objects parse input, drive a chat, write events, and store run state.
+* How the event stream and terminal outcome are ordered.
+* Which responsibilities stay with the host application.
+
+One RubyLLM chat turn is one AG-UI run. A run has one identity, one ordered
+stream of events and exactly one outcome, and the parts that decide those things
+are small enough to name:
+
+```
+POST RunAgentInput
+        │
+        ▼
+┌──────────────────┐   bounded, validated, typed   ┌────────────────┐
+│ Input.parse      │──────────────────────────────▶│ Run            │
+└──────────────────┘   + canonical digest          └────────────────┘
+                                                      │  │  │  │
+                          reserve (scope, thread, run) │  │  │  │
+                                    ┌─────────────────┘  │  │  │
+                                    ▼                    │  │  │
+                              ┌───────────┐              │  │  │
+                              │ RunStore  │◀─────────────┘  │  │
+                              └───────────┘   save/attach   │  │
+                                                             │  │
+             chat.complete { chunk }  ──▶  ┌─────────┐  events │  │
+             chat.before_tool_call   ──▶  │ Mapper  │─────────┘  │
+             chat.after_message      ──▶  └─────────┘            │
+                                                                 ▼
+                                     ┌──────────┐   one frame  ┌──────────┐
+                                     │ Emitter  │─────────────▶│ SSEWriter│──▶ IO
+                                     └──────────┘   per event   └──────────┘
+                                       record: sequence, status, terminal
+```
+
+## The boot contract
+
+```ruby
+require 'ruby_llm/ag_ui'
+```
+
+loads RubyLLM, `ag-ui-protocol`, Zeitwerk and the standard library, and nothing
+else. It does not load Rails, open a network connection or read provider
+credentials, and the test suite asserts that in a subprocess rather than by
+inspection (`spec/integration/core_load_spec.rb`).
+
+Two things are deliberately eager:
+
+- **Errors** (`lib/ruby_llm/ag_ui/error.rb`) are ignored by Zeitwerk and
+  `require`d directly, so a host can `rescue RubyLLM::AgUI::InputError` before
+  anything has been autoloaded.
+- **The namespace itself** (`RubyLLM::AgUI`, with `configure`, `config` and
+  `reset_configuration!`) lives in `lib/ruby_llm/ag_ui.rb`, because everything
+  else hangs off it.
+
+The Rails adapter under `lib/ruby_llm/ag_ui/rails/` is ignored by the loader and
+loaded only when `Rails::Railtie` is already defined. A pure-Ruby host never
+loads ActiveRecord or ActionController.
+
+`RubyLLM::AgUI` does not define or reopen the top-level `AgUi` namespace: that
+belongs to the `ag-ui` gem, and this gem talks to the protocol SDK as
+`::AgUiProtocol`. Inside the namespace the framework is `::Rails` for the same
+reason.
+
+## The pieces
+
+| Component | Owns | Does not own |
+|---|---|---|
+| `Input` / `Parser` / `MessageParser` | Bounding the body, decoding JSON, stripping unknown members, validating shapes, computing the canonical `digest`. | Trust. Nothing a client sends grants a privilege. |
+| `Run` | The turn: reserve identity, drive the chat, project callbacks, close and report the outcome. | Authentication, authorization, transport, chat construction. |
+| `Mapper` | Which AG-UI events a RubyLLM signal becomes, and the ordering between them. Returns arrays; writes nothing. | Sequence numbers, persistence, the terminal event. |
+| `Emitter` | Writing events, advancing the run record's sequence, persisting a terminal outcome before writing it, closing open content first. | Which events; the outcome. |
+| `SSEWriter` | Framing events as `text/event-stream` on any object with `#write`. | The connection, buffering, keep-alive policy. |
+| `Protocol` | The two 1.0 shapes `ag-ui-protocol` 0.2.0 cannot express, plus factories shared by the live and reconnect paths. | Schema evolution. |
+| `Store::Base` / `MemoryStore` / `Rails::ActiveRecordStore` | Run identity, interrupts, redemption. | Chat history, message ids, tool output. |
+| `RunRecord` / `Interrupt` | An immutable value per run and per approval pause, with legal transitions only. | Wire shapes. |
+| `Resume` / `Reconnect` | Answering a previous run's interrupts; serving a run that already ended. | Permission. A resume is a request. |
+| `Redaction` / `ErrorSanitizer` | What may appear on the wire: payload shapes without content, fixed error messages and codes. | Deciding what the host considers secret; that is the host's policy. |
+| `Coverage` | The 31-type audit against the pinned schema. | What the SDK supports. |
+
+## The run, step by step
+
+1. **Parse.** `Input.parse` bounds the body (`config.max_input_bytes`), decodes
+   it, strips top-level members the pinned schema does not define (warnings are
+   logged; `strict: true` rejects instead), validates message/tool/context
+   counts and shapes, and freezes the result with a canonical digest.
+2. **Reserve.** `Run` asks the store for `(scope, threadId, runId)`. The scope
+   must be a non-empty String the host built from authenticated identity. A
+   fresh key reserves; the same key with the same digest attaches; the same key
+   with a different digest is a conflict; a non-terminal record that is not
+   attachable is refused (`StreamError`) rather than streamed twice.
+3. **Open.** `RUN_STARTED` carries `protocolVersion` and the accepted input, so
+   the client can see exactly what the host accepted.
+4. **Drive.** `Run` registers one `before_tool_call`, one `after_message` and
+   one streaming block on the chat, then calls `Chat#complete`. RubyLLM owns the
+   agent loop: model calls, tool execution, approval pauses, cancellation
+   checkpoints.
+5. **Project.** Each callback hands the mapper its RubyLLM value and gets back
+   the events to write. The mapper is a state machine: a text message opens on
+   its first non-empty chunk and closes before a tool call, a phase change or the
+   terminal event; a tool call opens when its id and name are both known, streams
+   its argument deltas as received, and closes before it runs; one step per phase
+   (`completion`, `tool`) so consecutive steps never overlap.
+6. **Write.** The emitter writes the events as SSE, advancing the run record's
+   sequence by one per event.
+7. **Close and report.** Open content is closed, then the outcome is persisted
+   and only then written: `RUN_FINISHED` with `success`, `interrupt` or
+   `cancelled`, or `RUN_ERROR` with a sanitized message and code. A chat paused
+   on anything the protocol cannot express is a failure, not a success.
+
+## Invariants
+
+- **One outcome per run.** `RunRecord` transitions from `reserved` to `started`
+  and then to exactly one of `succeeded`, `interrupted`, `cancelled`, `failed`.
+  A terminal record accepts no new start, and `finish` records the first failure
+  and keeps it.
+- **Content before terminal.** No run ends with a text message, tool call or step
+  still open: a client that never sees `*_END` waits forever.
+- **Terminal before transport.** The outcome is stored before it is written, so
+  a socket that dies after the decision cannot cause a second execution.
+- **Sequence, not wall clock.** Every event advances the record's sequence; a
+  reconnect orders what it serves by that number.
+- **Delta replay is forbidden.** A reconnect serves `RUN_STARTED`,
+  `STATE_SNAPSHOT` (when recorded) and the terminal event. Never text or tool
+  deltas: replaying them draws text twice, and re-running a tool repeats the
+  side effect.
+- **Closed is final.** RubyLLM's callbacks are additive and cannot be removed, so
+  the callbacks a run registered stay attached to the chat. A mapper that has
+  closed its run therefore maps nothing further; the next turn is a different run
+  with its own ids, sequence and record.
+
+## Concurrency
+
+RubyLLM may run local tools on worker threads and appends tool results in the
+caller's thread, so `Run` maps and writes under one mutex. That keeps the event
+order consistent with the mapper's state; it does not make a run parallel.
+
+Two streams for one live run are refused, not merged: relaying one run to two
+clients is a transport the gem does not own. Two requests for one run identity
+are resolved by the store, and the store's redemption step is the authoritative
+race guard for a resume. The loser is told the answer was already recorded
+instead of running the tool twice.
+
+## Storage
+
+A record is a value object; stores keep values. `RunRecord#to_h` is the reporting
+shape (no interrupt argument digests, no creation times), and `#to_storage` is
+the durable shape a store round-trips through JSON. `ruby_llm_ag_ui_runs` (the
+Rails store) is one row per run: scope, thread, run, digest, status, sequence,
+snapshot, failure, interrupts.
+
+Why the scope must be a String: an arbitrary object hashes by identity, so the
+same actor would produce a different key on the next request and a retry would
+execute the run again. A String built from authenticated identity is stable
+across requests and processes, which is the property the reservation needs.
+
+## Extension points
+
+| Need | Hook |
+|---|---|
+| Durable or shared run identity | `config.run_store`, or `store:` per run. Implement the `Store::Base` interface. |
+| A different redaction policy | `config.redact`, or `redact:` per run. |
+| Deterministic time in tests | `config.clock`, or `clock:` per run. |
+| A shorter/longer approval window | `config.interrupt_ttl`, or `expires_in:` per run. |
+| A different transport | Write to your own object: the gem needs `#write`. |
+| A different server | Any Rack server; the Rails concern is one way to get a live response. |
+
+## Non-goals
+
+The gem is not an AG-UI SDK, a schema fork, a chat UI, a CopilotKit runtime, or a
+second agent framework. It does not own conversation history, message ids, tool
+authorization, or the decision to run a tool. It does not open connections, spawn
+jobs or buffer frames.
+
+See [Protocol Coverage]({% link _reference/protocol-coverage.md %}) for the wire events,
+[Security and Deployment]({% link _advanced/security-and-deployment.md %}) for the threat model, and
+[Rails Integration]({% link _advanced/rails-integration.md %}) for the adapter.

data/docs/_getting_started/whats-new-in-0-1.md

@@ -0,0 +1,41 @@
+---
+layout: default
+title: "What's New in 0.1"
+nav_order: 0
+description: Use the first RubyLLM AG-UI release to stream, resume, cancel, and reconnect agent runs.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to install version 0.1.
+* Which run lifecycle features it provides.
+* Which compatibility checks still need a real application.
+
+## Install the First Release
+
+```ruby
+gem 'ruby_llm-ag_ui', '~> 0.1.0'
+```
+
+Use Ruby 3.2 or later, RubyLLM 2.1 or later within version 2, and `ag-ui-protocol` 0.2. Follow [Getting Started]({% link _getting_started/getting-started.md %}) to create your first run.
+
+## Stream One Chat Turn as One Run
+
+The gem validates `RunAgentInput` and maps RubyLLM text, tool, and lifecycle callbacks to AG-UI events. An SSE writer sends each encoded event to the client. See [Streaming Runs]({% link _core_features/streaming-runs.md %}) and [Protocol Coverage]({% link _reference/protocol-coverage.md %}).
+
+## Pause, Resume, Cancel, and Reconnect
+
+Tool approval pauses use interrupts bound to their tool calls. Your host authorizes the actor and records the decision before resuming. Cancellation produces the cancelled outcome. A retry for a completed run replays its recorded state and terminal event. See [Approval and Resume]({% link _core_features/approval-and-resume.md %}) and [Reconnects]({% link _core_features/reconnects.md %}).
+
+## Add the Optional Rails Adapter
+
+The adapter supplies a streaming controller concern, an ActiveRecord run store, and an installation generator. The pure-Ruby entrypoint does not load Rails. Follow [Rails Integration]({% link _advanced/rails-integration.md %}).
+
+## Check Your Application's Compatibility
+
+Offline checks cover the mapping, schema, lifecycle, store, and adapter behavior. A release does not establish interoperability with every AG-UI client or live provider. Read [Compatibility]({% link _reference/compatibility.md %}) and record your application checks before making those claims.

data/docs/_reference/api-reference.md

@@ -0,0 +1,26 @@
+---
+layout: default
+title: API Reference
+nav_order: 1
+guide: false
+description: Browse RDoc pages generated from classes and methods in the gem source.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+The [API reference]({{ '/api/' | relative_url }}) opens on the `RubyLLM` module. The generated pages follow the RDoc comments in `lib/`.
+
+| Build with | Reference |
+| --- | --- |
+| Configure defaults | [`RubyLLM::AgUI::Configuration`]({{ '/api/RubyLLM/AgUI/Configuration.html' | relative_url }}) |
+| Parse a request | [`RubyLLM::AgUI::Input`]({{ '/api/RubyLLM/AgUI/Input.html' | relative_url }}) |
+| Stream a chat turn | [`RubyLLM::AgUI::Run`]({{ '/api/RubyLLM/AgUI/Run.html' | relative_url }}) |
+| Inspect event coverage | [`RubyLLM::AgUI::Coverage`]({{ '/api/RubyLLM/AgUI/Coverage.html' | relative_url }}) |
+| Store run state | [`RubyLLM::AgUI::Store::MemoryStore`]({{ '/api/RubyLLM/AgUI/Store/MemoryStore.html' | relative_url }}) |
+
+For Markdown, start with the [class index]({{ '/api/index.md' | relative_url }}). Every HTML class page has a matching `.md` page.
+
+The reference is generated from source comments with RDoc. Build it locally with `docs/bin/build-api.sh tmp/api`.

data/docs/_reference/compatibility.md

@@ -0,0 +1,130 @@
+---
+layout: default
+title: "Compatibility"
+nav_order: 2
+description: Check the dependency versions and behaviors that this repository verifies.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* Which runtime and protocol dependency ranges the gem supports.
+* What the local and CI suites assert.
+* Which client and provider claims remain unverified.
+
+What this gem is checked against, what it is not, and what changes when a
+dependency does.
+
+## Supported versions
+
+| Component | Range | Verified |
+|---|---|---|
+| Ruby | `>= 3.2` | 3.2, 3.3, 3.4 in CI; 3.3.5 locally |
+| RubyLLM | `>= 2.1`, `< 3.0` | 2.1.1 (callback, approval and cancellation behavior read from its source) |
+| `ag-ui-protocol` | `~> 0.2.0` | 0.2.0 |
+| Rails (adapter only) | `railties`, `actionpack`, `activerecord` `>= 8.0` | 8.0.x and 8.1.x in CI |
+| AG-UI schema | pinned commit `89cedd3fd549feeee41e50e1d7c6d373e549241a` | vendored, SHA-256 recorded in [AG-UI Protocol Coverage]({% link _reference/protocol-coverage.md %}) |
+
+The pure-Ruby core depends only on `ruby_llm` and `ag-ui-protocol`. Rails,
+`ToolViews`, `OpenUI` and `OddlyDock` are not runtime dependencies, and the Rails
+adapter is only loaded when `Rails::Railtie` is already defined.
+
+## What is asserted, and how
+
+| Claim | How it is checked |
+|---|---|
+| `require 'ruby_llm/ag_ui'` loads no Rails, opens no connection, reads no credentials | `spec/integration/core_load_spec.rb` runs the require in a subprocess and inspects what it loaded |
+| Every emitted event is a valid AG-UI 1.0 event | mapper and run specs validate each encoded event against the vendored schema (`SchemaHelper`) |
+| The 31-type coverage map is the schema's own union | `spec/ruby_llm/ag_ui/coverage_spec.rb` compares the pinned list with `Coverage`, and the SDK enum at runtime |
+| The SDK's five legacy `THINKING_*` constants are never counted as 1.0 | the same spec asserts `LEGACY_SDK_ONLY` is absent from the map |
+| Text, tool and lifecycle sequences are ordered and closed | mapper specs, including partial arguments, a nil chunk, a tool that raises, and a thinking-only chunk |
+| One outcome per run, and the outcome matches what happened | run specs: success, interrupt, cancelled, sanitized failure, unsupported pause |
+| `requires_approval` → interrupt → resume executes the tool once | run specs drive a fake chat through the pause, approve, deny, replay and expiry cases |
+| Identity is reserved, replayed and never re-executed | store specs (memory and ActiveRecord), run specs for conflict, reconnect and live-run refusal |
+| The Rails adapter serves a run and refuses invalid requests before committing | adapter specs with a controller double, and an end-to-end `spec/integration/rails_adapter_spec.rb` |
+| The installer resolves the documented command | `spec/ruby_llm/ag_ui/generators/install_generator_spec.rb` |
+| The installed gem generates a working migration and initializer | `bin/verify-package --rails` generates files and migrates the table up and down in SQLite |
+| `ruby_llm-ag_ui` installs outside the checkout | `bin/verify-package` resolves dependencies in a fresh gem home and loads the packaged core |
+
+The RSpec suite runs offline with fakes and no provider credentials. Package verification uses the network only to install dependencies, then runs its core and Rails checks without a provider. Its advisory check includes the actual default-library gem versions activated by the isolated core install.
+
+## What is not asserted
+
+- **Real AG-UI clients** (CopilotKit, `@ag-ui/client`, any other consumer). No
+  client has been recorded against this producer. The events are schema-valid and
+  the ordering rules the protocol documents are enforced, but "a specific client
+  renders this correctly" is a separate claim, and it is not made here.
+- **Live providers.** `spec/live/live_run_spec.rb` is the opt-in check
+  (`RUBY_LLM_LIVE=1`, plus a provider key); it is skipped in the default suite.
+  Provider behavior in 2.1.1 is derived from its source, not from a recorded
+  session.
+- **Every RubyLLM patch release in the `>= 2.1, < 3.0` range.** The upper bound
+  is enforced by the gemspec; the verified version is 2.1.1.
+- **Rails versions before 8.0.** The adapter uses `Rails.setup!` and an
+  initializer, and its specs run on 8.0/8.1. It may work on 7.2 and it is not
+  tested there.
+- **Databases other than SQLite** for the ActiveRecord store. The store uses a
+  unique index and `with_lock`; PostgreSQL and MySQL should behave the same, and
+  that is untested.
+
+## Deliberate behavior worth knowing
+
+These are choices, not gaps, and each has a reason:
+
+- **Tool results are `[redacted]` by default.** Redaction keeps the payload's
+  shape and withholds its content until a host opts out. A client will see
+  `[redacted]` until you configure a policy.
+- **A resume run emits `TOOL_CALL_RESULT` without repeating
+  `TOOL_CALL_START`.** The call was already reported in the run that interrupted;
+  repeating it would duplicate the call in the client's conversation.
+- **`MESSAGES_SNAPSHOT` is never produced.** History is the host's, and the gem
+  will not re-id it. `STATE_SNAPSHOT` is produced, on a reconnect.
+- **No `ACTIVITY_*`, `REASONING_*`, `RAW` or `SUBAGENT_*` events.** RubyLLM 2.x
+  exposes no data for them on the supported path, and the gem does not invent
+  events. A thinking-only chunk produces nothing.
+- **Message ids are the gem's** (`run-<id>:a<n>`), scoped to the run, because
+  RubyLLM streaming chunks carry no message id.
+- **Steps are per phase** (`completion`, `tool`), named `step-<n>` per run.
+- **Client-supplied tools are never registered.** `input.tools` is reported and
+  ignored.
+- **Two live streams for one run are refused**, not merged; a run that already
+  ended is served by reconnect instead.
+
+## When a dependency moves
+
+**A new `ag-ui-protocol` 0.2.x** that adds a schema type will fail the coverage
+spec's runtime comparison, which is the point: the map has to be updated
+deliberately, with a status and a reason.
+
+**`ag-ui-protocol` 0.3+** would need `Protocol` re-checked first: the gem
+subclasses `Model` and `BaseEvent` for the cancelled outcome, the versioned
+`RUN_STARTED` and the run-finished shape. The gaps listed in
+the [protocol coverage guide]({% link _reference/protocol-coverage.md %}) may be closed upstream, in which case
+the local subclasses should be removed rather than kept.
+
+**A new RubyLLM 2.x minor** can change the callback contract (`before_tool_call`,
+`after_message`, `complete`'s streaming block), approval state (`waiting?`,
+`awaiting_approval?`, `pending_approvals`, `approve`, `deny`) or the shape of
+chunks and messages. The mapper and run specs pin all of it, so an upgrade fails
+loudly instead of silently dropping content. A 3.0 would need a new adapter
+layer; the gemspec refuses it.
+
+**A new AG-UI schema commit** is a deliberate change: vendor the file, update
+`Protocol::SCHEMA_COMMIT` and the SHA-256 in
+the [protocol coverage guide]({% link _reference/protocol-coverage.md %}), then let the coverage and schema
+specs tell you what moved.
+
+## Reporting an incompatibility
+
+Open an issue with the versions from `RubyLLM::AgUI.config.to_h`, the event types
+that went wrong, and whether a real client or a live provider was involved. A
+redacted trace is enough; do not paste credentials or raw tool payloads.
+
+## Next Steps
+
+* [AG-UI Protocol Coverage]({% link _reference/protocol-coverage.md %}) - inspect event support.
+* [Upgrading]({% link _reference/upgrading.md %}) - record breaking dependency changes.

data/docs/_reference/protocol-coverage.md

@@ -0,0 +1,175 @@
+---
+layout: default
+title: "AG-UI Protocol Coverage"
+nav_order: 1
+description: See how this producer handles each event in the pinned AG-UI 1.0 schema.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+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
+
+| | |
+|---|---|
+| Repository | <https://github.com/ag-ui-protocol/ag-ui> |
+| Commit | `89cedd3fd549feeee41e50e1d7c6d373e549241a` |
+| File | `docs/spec/1.0/schema.json` |
+| Vendored copy | `spec/fixtures/schema/ag-ui-1.0.schema.json` |
+| SHA-256 | `4b5c93226838a0e72d88e6c5df20633c686c49fcb75d9be2815c6cbf9e48e71a` |
+
+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)
+
+| Event type | Family | When |
+|---|---|---|
+| `RUN_STARTED` | run | Opens a reserved run; declares `protocolVersion` and echoes the accepted input. |
+| `RUN_FINISHED` | run | Success, interrupt or cancelled outcome; never a raw partial. |
+| `RUN_ERROR` | run | Sanitized message and code; never raw exception text. |
+| `STEP_STARTED` | run | One step per RubyLLM phase (completion, tool round). |
+| `STEP_FINISHED` | run | Closed before the terminal event. |
+| `TEXT_MESSAGE_START` | text | Opened on the first non-empty assistant chunk. |
+| `TEXT_MESSAGE_CONTENT` | text | One delta per non-empty `chunk.content`, in order. |
+| `TEXT_MESSAGE_END` | text | Closed before a tool call, a phase change or the terminal event. |
+| `TOOL_CALL_START` | tool | Emitted when a call is observed before it runs. |
+| `TOOL_CALL_ARGS` | tool | Arguments as received; never re-synthesized. |
+| `TOOL_CALL_END` | tool | Closed before the call runs or the run ends. |
+| `TOOL_CALL_RESULT` | tool | The tool result, after the host redaction policy. |
+| `STATE_SNAPSHOT` | state | On a reconnect: the state the host gave the run. |
+
+### Optional (1)
+
+| Event type | Family | When |
+|---|---|---|
+| `CUSTOM` | raw/custom | Only safe, documented host extensions. Nothing in the gem emits one today. |
+
+### Host-owned, not produced (2)
+
+| Event type | Family | Why the gem does not produce it |
+|---|---|---|
+| `MESSAGES_SNAPSHOT` | state | The conversation belongs to the host. Producing one would mean re-synthesizing message ids the gem did not mint, which a client would then render as new messages. |
+| `STATE_DELTA` | state | Deltas describe a change the host made. The gem never invents a patch, and it has no API that publishes one. |
+
+### Not produced (15)
+
+| Event type | Family | Why |
+|---|---|---|
+| `TEXT_MESSAGE_CHUNK` | text | Convenience form of the explicit triad; the gem emits `START`/`CONTENT`/`END`. |
+| `TOOL_CALL_CHUNK` | tool | Convenience form; the gem emits the explicit triad. |
+| `ACTIVITY_SNAPSHOT` | activity | No `ACTIVITY_*` projection yet; RubyLLM's progress signals are not mapped. |
+| `ACTIVITY_DELTA` | activity | Same: no progress projection, and no invented patches. |
+| `RAW` | raw/custom | The gem never passes provider payloads through. |
+| `REASONING_START` | reasoning | Private reasoning is not emitted until a host opts in, and there is no opt-in yet. |
+| `REASONING_MESSAGE_START` | reasoning | A chunk that carries thinking is ignored. |
+| `REASONING_MESSAGE_CONTENT` | reasoning | Same. |
+| `REASONING_MESSAGE_END` | reasoning | Nothing opens a reasoning block to close. |
+| `REASONING_MESSAGE_CHUNK` | reasoning | Convenience form; not emitted. |
+| `REASONING_END` | reasoning | Nothing opens a reasoning block to close. |
+| `REASONING_ENCRYPTED_VALUE` | reasoning | RubyLLM 2.x exposes no encrypted reasoning value. |
+| `SUBAGENT_STARTED` | subagents | RubyLLM 2.x runs one chat; there is no subagent data. |
+| `SUBAGENT_FINISHED` | subagents | Same. |
+| `SUBAGENT_ERROR` | subagents | Same. |
+
+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:
+
+| Situation | Terminal event |
+|---|---|
+| The chat completed | `RUN_FINISHED` with `{"type":"success"}` |
+| The chat paused on `requires_approval` | `RUN_FINISHED` with `{"type":"interrupt","interrupts":[...]}` |
+| The chat was cancelled (`Chat#cancel`) | `RUN_FINISHED` with `{"type":"cancelled"}` |
+| The run failed | `RUN_ERROR` with a sanitized `message` and a `code` |
+| The chat paused on something the protocol cannot express | `RUN_ERROR` (`unsupported_run_state`), never a success |
+
+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.
+
+| ID | Gap | This gem's handling |
+|---|---|---|
+| SDK-GAP-01 | No `cancelled` run outcome. | `RubyLLM::AgUI::Protocol::CancelledOutcome`, a schema-valid `cancelled` outcome. |
+| SDK-GAP-02 | `RunStartedEvent` has no `protocolVersion`. | `RubyLLM::AgUI::Protocol::RunStartedEvent` adds it, defaulting to `"1.0"`. |
+| SDK-GAP-03 | No JSON → `RunAgentInput` parser. | `RubyLLM::AgUI::Input.parse`, with size and schema bounds. |
+| SDK-GAP-04 | No `SUBAGENT_STARTED`/`_FINISHED`/`_ERROR` constants. | Not produced: RubyLLM 2.x has no subagent data to report. |
+| SDK-GAP-05 | Five legacy `THINKING_*` constants that 1.0 does not define. | Never emitted. `Coverage` excludes them from the 31 and the suite asserts it. |
+
+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
+
+```ruby
+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]({% link _core_features/streaming-runs.md %}) - follow event order and outcomes.
+* [Compatibility]({% link _reference/compatibility.md %}) - see what this repository verifies.

data/docs/_reference/release-history.md

@@ -0,0 +1,22 @@
+---
+layout: default
+title: Release History
+nav_order: 9
+guide: false
+description: Review RubyLLM AG-UI releases, newest first, with highlights and upgrade guidance.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+{% if site.docs_unreleased %}This build follows `main`. The latest stable release is `{{ site.version }}`.
+{% else %}This documentation describes version `{{ site.version }}`. Use its tag and release notes to identify the exact source.
+{% endif %}
+
+| Release | Date | Highlights |
+| --- | --- | --- |
+| [0.1.0](https://github.com/yorzi/ruby_llm-ag-ui/releases/tag/v0.1.0) | 2026-10-18 | [First release]({% link _getting_started/whats-new-in-0-1.md %}): AG-UI event mapping, approval and resume, cancellation, reconnect, and the optional Rails adapter |
+
+To move an application from one release to the next, follow [Upgrading]({% link _reference/upgrading.md %}).

data/docs/_reference/releasing.md

@@ -0,0 +1,54 @@
+---
+layout: default
+title: Releasing
+nav_order: 10
+description: Verify an installed gem artifact and publish its matching version tag through RubyGems trusted publishing.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to check a release artifact outside the checkout.
+* Which settings bind RubyGems to the release workflow.
+* How a version tag publishes the gem and its documentation.
+
+## Verify the Package
+
+```bash
+bundle exec rake
+bundle exec bundle-audit check --update
+bundle exec rake build
+bundle exec ruby bin/verify-package --rails --audit
+docs/bin/build.sh
+```
+
+The package check installs dependencies in a fresh temporary gem home and requires the installed artifact from outside the checkout. It verifies the core entrypoint, shipped templates and guides, and input parsing. With `--rails`, it invokes the documented generator and migrates its table up and down in SQLite. With `--audit`, it checks the actually activated core dependencies against the advisory database.
+
+These checks make no live provider call. Keep provider and client interoperability evidence in [Compatibility]({% link _reference/compatibility.md %}).
+
+## Configure Trusted Publishing
+
+Before the first tag, register a pending trusted publisher on RubyGems with gem name `ruby_llm-ag_ui`, GitHub owner `yorzi`, repository `ruby_llm-ag-ui`, workflow `release.yml`, and environment `release`. The workflow uses a short-lived GitHub OIDC identity instead of a stored RubyGems API key.
+
+## Prepare the Release Commit
+
+Match the version in `lib/ruby_llm/ag_ui/version.rb` and `docs/_config.yml`. Set `released: true`, add a dated CHANGELOG section, update [Release History]({% link _reference/release-history.md %}), and record upgrade steps in [Upgrading]({% link _reference/upgrading.md %}). For a minor release, add its What's New guide.
+
+Push the completed commit to `main` and wait for CI to pass. Tag that exact commit:
+
+```bash
+git tag -a v{{ site.version }} -m "Release {{ site.version }}"
+git push origin v{{ site.version }}
+```
+
+Replace the example tag with the version you are releasing. The `Release Gem` workflow rejects a tag that differs from the gem or docs version, or lacks a CHANGELOG section. It runs offline checks, the advisory audit, and isolated package verification before publishing.
+
+## Confirm Publication
+
+On success, the workflow creates a GitHub Release with the gem, checksum, and CHANGELOG notes. The Docs workflow runs after the release workflow succeeds. It publishes the tagged version at `/` and current `main` at `/next/`.
+
+Check the version on RubyGems, the GitHub Release assets, and the documentation installation command. If a publish attempt fails, inspect its logs before retrying. A published RubyGems version cannot be overwritten.