ruby_llm-ag_ui 0.1.0

data/docs/_reference/third-party-notices.md

@@ -0,0 +1,82 @@
+---
+layout: default
+title: "Third-Party Notices"
+nav_order: 5
+guide: false
+description: Review licenses and provenance for runtime, optional, and development dependencies.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+`ruby_llm-ag_ui` is released under the MIT License. See
+[the MIT license in the repository](https://github.com/yorzi/ruby_llm-ag-ui/blob/main/LICENSE.txt).
+
+It is an unofficial community project. It is not affiliated with, endorsed by, or
+maintained by the RubyLLM maintainers or the AG-UI protocol maintainers.
+
+## Runtime dependencies
+
+| Project | License | How this gem uses it |
+|---|---|---|
+| [RubyLLM](https://github.com/crmne/ruby_llm) | MIT | The agent loop this gem projects: `Chat#complete`, the streaming block, `before_tool_call`, `after_message`, approval state and cancellation. |
+| [ag-ui-protocol](https://github.com/ag-ui-protocol/ag-ui) (Ruby SDK, `~> 0.2.0`) | MIT | Event models, `BaseEvent`, the encoder and the event-type constants. |
+| [Zeitwerk](https://github.com/fxn/zeitwerk) | MIT | Autoloading the gem's own files. |
+| Ruby standard-library gems `cgi`, `resolv`, `uri`, `zlib` | Ruby or BSD-2-Clause | Patched CGI, DNS resolution, URL, and compression dependencies used by the runtime dependency chain. |
+
+The gem's direct runtime dependencies are `ruby_llm`, `ag-ui-protocol`, `cgi`, `resolv`, `uri`, and `zlib`.
+Zeitwerk arrives through RubyLLM and is used directly.
+
+## Optional: Rails
+
+Rails is **not** a runtime dependency. When a host already has it, the adapter
+uses:
+
+| Project | License |
+|---|---|
+| [Rails](https://github.com/rails/rails) (`railties`, `actionpack`, `activerecord`) | MIT |
+| [SQLite3](https://github.com/sparklemotion/sqlite3-ruby) (development/test only) | BSD-3-Clause |
+
+## Vendored file
+
+`spec/fixtures/schema/ag-ui-1.0.schema.json` is a verbatim copy of
+`docs/spec/1.0/schema.json` from the AG-UI repository at commit
+`89cedd3fd549feeee41e50e1d7c6d373e549241a`.
+
+- Upstream: <https://github.com/ag-ui-protocol/ag-ui/blob/89cedd3fd549feeee41e50e1d7c6d373e549241a/docs/spec/1.0/schema.json>
+- License: MIT (the AG-UI repository's `LICENSE` at the same commit)
+- SHA-256: `4b5c93226838a0e72d88e6c5df20633c686c49fcb75d9be2815c6cbf9e48e71a`
+- Provenance note: [the vendored schema README](https://github.com/yorzi/ruby_llm-ag-ui/blob/main/spec/fixtures/schema/README.md)
+
+It is used only by the test suite and is never served, re-published or modified.
+
+## Development dependencies
+
+None of these are shipped to users.
+
+| Project | License |
+|---|---|
+| RSpec | MIT |
+| RuboCop, `rubocop-rake`, `rubocop-rspec` | MIT |
+| `json_schemer` | MIT |
+| WebMock | MIT |
+| SimpleCov | MIT |
+| dotenv | MIT |
+| Rake | MIT |
+| bundler-audit | GPL-3.0-or-later |
+
+## What this gem does not include
+
+No code, templates, assets or schema from ToolViews, OpenUI, OddlyDock or any
+AG-UI client is bundled, copied or required. No provider SDK is vendored: RubyLLM
+supplies provider access, and this gem never talks to a provider directly.
+
+## Names and trademarks
+
+"RubyLLM" and "AG-UI" are used only to describe what this gem extends. Neither
+project's name, logo or maintainers are used to imply endorsement. The gem is
+published as `ruby_llm-ag_ui` under the author's own name and namespace
+(`RubyLLM::AgUI`), and it does not define or reopen the top-level `AgUi`
+namespace owned by the `ag-ui` gem.

data/docs/_reference/upgrading.md

@@ -0,0 +1,42 @@
+---
+layout: default
+title: Upgrading
+nav_order: 2
+description: Move a RubyLLM AG-UI application to the next release, one release at a time.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to move between versioned releases.
+* Where to find changes that need code updates.
+
+## One Release at a Time
+
+Version `0.1.0` is the first release. There is no earlier published version to upgrade from. Start with [Getting Started]({% link _getting_started/getting-started.md %}). For future releases, upgrade one release at a time.
+
+## Install Version 0.1
+
+```ruby
+gem 'ruby_llm-ag_ui', '~> 0.1.0'
+```
+
+If you used an untagged development checkout, review [Configuration]({% link _getting_started/configuration.md %}) and [Rails Integration]({% link _advanced/rails-integration.md %}) before changing the dependency. No compatibility with earlier untagged checkouts is promised.
+
+## Use the Full Generator Command
+
+Untagged development checkouts registered the shorter `ruby_llm:ag_ui` namespace. Version 0.1 registers the documented installation command:
+
+```bash
+# Before, on an untagged checkout
+bin/rails generate ruby_llm:ag_ui
+
+# Version 0.1
+bin/rails generate ruby_llm:ag_ui:install
+```
+
+Existing generated tables and initializers do not need to be regenerated for this command-name correction.

data/docs/index.md

@@ -0,0 +1,53 @@
+---
+layout: home
+title: "RubyLLM AG-UI"
+description: "Run RubyLLM chats as AG-UI 1.0 streams with validated input, approval pauses, cancellation, and optional Rails integration."
+permalink: /
+hero:
+  name: "RubyLLM AG-UI"
+  text: "Run RubyLLM chats as AG-UI agent runs"
+  tagline: "An unofficial Ruby gem for connecting RubyLLM applications to AG-UI clients."
+  actions:
+    - theme: brand
+      text: Get started
+      link: /getting-started/
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/yorzi/ruby_llm-ag-ui
+features:
+  - title: Ordered event streams
+    details: Map one RubyLLM chat turn to one AG-UI run with a single recorded outcome.
+    link: /streaming-runs/
+    link_text: Stream a run
+  - title: Safe input and approval
+    details: Validate RunAgentInput and resume approved tool calls on a new run.
+    link: /input-validation/
+    link_text: Validate input
+  - title: Optional Rails adapter
+    details: Add a controller concern and a durable ActiveRecord store to a Rails app.
+    link: /rails-integration/
+    link_text: Use with Rails
+---
+
+## Install
+
+```sh
+{% if site.docs_unreleased %}bundle add ruby_llm-ag_ui --git https://github.com/yorzi/ruby_llm-ag-ui --branch main{% else %}bundle add ruby_llm-ag_ui --version {{ site.version }}{% endif %}
+```
+
+## Parse a request
+
+```ruby
+require 'ruby_llm/ag_ui'
+
+input = RubyLLM::AgUI::Input.parse({
+  'threadId' => 'thread-1',
+  'runId' => 'run-1',
+  'messages' => [{ 'id' => 'm1', 'role' => 'user', 'content' => 'Hello' }]
+})
+
+puts "#{input.thread_id}/#{input.run_id}"
+# => thread-1/run-1
+```
+
+[Get started]({% link _getting_started/getting-started.md %}) or read [how a run works]({% link _getting_started/overview.md %}).

data/lib/generators/ruby_llm/ag_ui/install_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module RubyLLM
+  module AgUI
+    module Generators
+      # `bin/rails generate ruby_llm:ag_ui:install`
+      #
+      # Creates the table the durable run store keeps run identity in, and an
+      # initializer that points the gem at it. Running it twice does nothing the
+      # second time, because a migration and an initializer are files, not
+      # state.
+      class InstallGenerator < ::Rails::Generators::Base
+        include ::Rails::Generators::Migration
+
+        namespace 'ruby_llm:ag_ui:install'
+        desc 'Create the ruby_llm-ag_ui run store table and its initializer.'
+        source_root File.expand_path('templates', __dir__)
+
+        def self.next_migration_number(dirname)
+          ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+        end
+
+        def create_migration_file
+          migration_template 'create_ruby_llm_ag_ui_runs.rb.tt',
+                             'db/migrate/create_ruby_llm_ag_ui_runs.rb'
+        end
+
+        def create_initializer
+          template 'initializer.rb.tt', 'config/initializers/ruby_llm_ag_ui.rb'
+        end
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/ag_ui/templates/create_ruby_llm_ag_ui_runs.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateRubyLlmAgUiRuns < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :ruby_llm_ag_ui_runs do |t|
+      t.string :scope, null: false
+      t.string :thread_id, null: false
+      t.string :run_id, null: false
+      t.string :digest, null: false
+      t.string :status, null: false
+      t.integer :sequence, null: false, default: 0
+      # The whole core record as JSON text: it is immutable (there is no partial
+      # update), and the gem encodes it, so the stored shape does not depend on
+      # the database's JSON type or the host's JSON encoder.
+      t.text :payload, null: false
+    end
+
+    # The identity a run is reserved under, and the guard that stops two workers
+    # from reserving it at once.
+    add_index :ruby_llm_ag_ui_runs, %i[scope thread_id run_id], unique: true
+    # Listing one thread's runs, newest first.
+    add_index :ruby_llm_ag_ui_runs, %i[scope thread_id status]
+  end
+end

data/lib/generators/ruby_llm/ag_ui/templates/initializer.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# An unofficial RubyLLM ecosystem extension. Rails is optional and the core is
+# pure Ruby, so this initializer is only about the choices a Rails host makes.
+RubyLLM::AgUI.configure do |config|
+  # Run identity must outlive the worker that reserved it: one run per
+  # (scope, thread_id, run_id), reserved before any provider work happens.
+  # Replace the in-process store, which is correct for one process only.
+  config.run_store = RubyLLM::AgUI::Rails::ActiveRecordStore.new
+
+  # Redaction is on by default and withholds tool result content until a host
+  # says what is safe to publish. Replace it with your own policy, or opt out
+  # with RubyLLM::AgUI::Redaction.method(:none).
+  # config.redact = RubyLLM::AgUI::Redaction.method(:none)
+
+  # How long an interrupt stays answerable, in seconds.
+  # config.interrupt_ttl = 900
+
+  # The largest request body the adapter will read, in bytes.
+  # config.max_input_bytes = 256_000
+
+  # Host-side diagnostics. Never receives prompts, tool payloads or credentials.
+  # config.logger = Rails.logger
+end

data/lib/ruby_llm/ag_ui/canonical.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # Deterministic serialization and hashing.
+    #
+    # Run identity depends on comparing an input with the one a retry sends.
+    # JSON object member order is not significant, so a naive hash of the raw
+    # bytes treats the same request as two. Canonical.dump sorts object keys
+    # recursively (like RubyLLM's ToolCall#arguments, so a call reloaded from a
+    # database hashes the same), producing a stable string to digest.
+    module Canonical
+      module_function
+
+      # A deterministic JSON string: object keys sorted by their byte length
+      # then value, arrays kept in order.
+      def dump(value)
+        JSON.generate(sort(value))
+      end
+
+      # The SHA-256 hex digest of the canonical form.
+      def digest(value)
+        Digest::SHA256.hexdigest(dump(value))
+      end
+
+      # A recursively key-sorted copy of +value+.
+      def sort(value)
+        case value
+        when Hash
+          value.sort_by { |key, _| [key.to_s.bytesize, key.to_s] }
+               .to_h { |key, nested| [key.to_s, sort(nested)] }
+        when Array
+          value.map { |item| sort(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/configuration.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # Global configuration for the gem. Hosts usually set it once at boot:
+    #
+    #   RubyLLM::AgUI.configure do |config|
+    #     config.run_store = MyRunStore.new
+    #     config.redact    = ->(kind, payload) { MyRedactor.call(kind, payload) }
+    #     config.logger    = Rails.logger
+    #   end
+    #
+    # Every value can be overridden per run by passing the matching keyword to
+    # RubyLLM::AgUI::Run.new.
+    class Configuration
+      # The object that reserves run identity and stores interrupts. Defaults
+      # to nil; set a RubyLLM::AgUI::Store::MemoryStore for single-process use,
+      # or a durable store for multi-process deployment.
+      attr_accessor :run_store
+
+      # A callable (kind, payload) — or (payload) — invoked before a tool result
+      # or activity payload reaches the wire. Return the value to publish.
+      #
+      # It defaults to RubyLLM::AgUI::Redaction.default, which keeps the
+      # payload's shape and withholds its content: the gem cannot know which
+      # part of a tool result is a secret, so it does not publish the raw value
+      # until a host says it is safe. Opt out with
+      # RubyLLM::AgUI::Redaction.method(:none), or replace it with your policy.
+      attr_writer :redact
+
+      # A Logger used for host-side diagnostics. Never receives prompts, raw
+      # tool payloads or credentials.
+      attr_accessor :logger
+
+      # The AG-UI protocol version this producer speaks, emitted on
+      # RUN_STARTED so a consumer can detect a downgrade.
+      attr_accessor :protocol_version
+
+      # Maximum accepted request body size in bytes.
+      attr_accessor :max_input_bytes
+
+      # Maximum number of messages accepted in RunAgentInput.
+      attr_accessor :max_messages
+
+      # Maximum number of tools accepted in RunAgentInput.
+      attr_accessor :max_tools
+
+      # Maximum number of context entries accepted in RunAgentInput.
+      attr_accessor :max_context
+
+      # How long an interrupt stays answerable, in seconds.
+      attr_accessor :interrupt_ttl
+
+      # A callable returning the current UTC Time. Injected in tests.
+      attr_accessor :clock
+
+      # Whether client-supplied message history is reconciled against
+      # host-stored history. Always off in the first release: client messages
+      # are never trusted as system or tool turns.
+      attr_accessor :allow_client_history
+
+      def initialize
+        @run_store = nil
+        @redact = Redaction.method(:default)
+        @logger = nil
+        @protocol_version = '1.0'
+        @max_input_bytes = 256_000
+        @max_messages = 500
+        @max_tools = 64
+        @max_context = 64
+        @interrupt_ttl = 900
+        @clock = -> { Time.now.utc }
+        @allow_client_history = false
+      end
+
+      # The redaction policy in force. Never nil: an unset or nil policy falls
+      # back to the default rather than publishing raw payloads.
+      def redact
+        @redact || Redaction.method(:default)
+      end
+
+      # Which policy is in force, for diagnostics: :default, :none or :custom.
+      def redaction
+        return :default if redact == Redaction.method(:default)
+        return :none if redact == Redaction.method(:none)
+
+        :custom
+      end
+
+      # The run store, or nil when the host has not configured one.
+      def run_store!
+        @run_store || raise(ConfigurationError, 'No run_store is configured. ' \
+                                                'Set RubyLLM::AgUI.config.run_store or pass store: to Run.new.')
+      end
+
+      # A snapshot of the configuration, for diagnostics and support reports.
+      # Never includes secrets.
+      def to_h
+        {
+          run_store: run_store&.class&.name,
+          redact: redaction,
+          protocol_version: protocol_version,
+          max_input_bytes: max_input_bytes,
+          max_messages: max_messages,
+          max_tools: max_tools,
+          max_context: max_context,
+          interrupt_ttl: interrupt_ttl,
+          allow_client_history: allow_client_history
+        }
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/coverage.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # The AG-UI 1.0 producer coverage map (FR-02).
+    #
+    # Every one of the 31 event types the pinned 1.0 schema defines is listed
+    # with the status this gem gives it. A producer is not required to
+    # manufacture events it has no data for; what it must never do is emit an
+    # event that the schema does not define, or misreport one it does.
+    #
+    # This is the gem's own audit against the pinned schema commit
+    # (RubyLLM::AgUI::Protocol::SCHEMA_COMMIT). It is not a claim about
+    # `ag-ui-protocol`, whose enum is compared separately below.
+    module Coverage
+      # The statuses an entry may have.
+      #   :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; the gem does not produce it
+      #   :not_produced — the producer has no data for it and never fabricates it
+      STATUSES = %i[produced optional host_owned not_produced].freeze
+
+      # Event types listed in the pinned docs/spec/1.0/schema.json Event union.
+      SCHEMA_EVENT_TYPES = %w[
+        TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END TEXT_MESSAGE_CHUNK
+        TOOL_CALL_START TOOL_CALL_ARGS TOOL_CALL_END TOOL_CALL_CHUNK TOOL_CALL_RESULT
+        STATE_SNAPSHOT STATE_DELTA MESSAGES_SNAPSHOT
+        ACTIVITY_SNAPSHOT ACTIVITY_DELTA
+        RAW CUSTOM
+        RUN_STARTED RUN_FINISHED RUN_ERROR STEP_STARTED STEP_FINISHED
+        REASONING_START REASONING_MESSAGE_START REASONING_MESSAGE_CONTENT
+        REASONING_MESSAGE_END REASONING_MESSAGE_CHUNK REASONING_END REASONING_ENCRYPTED_VALUE
+        SUBAGENT_STARTED SUBAGENT_FINISHED SUBAGENT_ERROR
+      ].freeze
+
+      FAMILIES = {
+        'TEXT_MESSAGE' => :text_messages,
+        'TOOL_CALL' => :tool_calls,
+        'STATE' => :state,
+        'MESSAGES' => :state,
+        'ACTIVITY' => :activity,
+        'RAW' => :raw_custom,
+        'CUSTOM' => :raw_custom,
+        'RUN' => :run_lifecycle,
+        'STEP' => :run_lifecycle,
+        'REASONING' => :reasoning,
+        'SUBAGENT' => :subagents
+      }.freeze
+
+      # Producer status and a one-line reason, keyed by event type.
+      STATUS = {
+        'RUN_STARTED' => [:produced, 'Opens a reserved run; declares protocolVersion.'],
+        'RUN_FINISHED' => [:produced, 'Success, interrupt or cancelled outcome; never a raw partial.'],
+        'RUN_ERROR' => [:produced, 'Sanitized message and code; never raw exception text.'],
+        'STEP_STARTED' => [:produced, 'One step per RubyLLM completion or tool round.'],
+        'STEP_FINISHED' => [:produced, 'Closed before the terminal event.'],
+        'TEXT_MESSAGE_START' => [:produced, 'Opened on the first streamed assistant text chunk.'],
+        'TEXT_MESSAGE_CONTENT' => [:produced, 'One delta per non-empty chunk.content.'],
+        'TEXT_MESSAGE_END' => [:produced, 'Closed before a tool round or the terminal event.'],
+        'TEXT_MESSAGE_CHUNK' => [:not_produced, 'Convenience form; the gem emits the explicit triad.'],
+        'TOOL_CALL_START' => [:produced, 'Emitted when a call is observed before it runs.'],
+        'TOOL_CALL_ARGS' => [:produced, 'Arguments as received; never re-synthesized.'],
+        'TOOL_CALL_END' => [:produced, 'Closed before the call runs or the run ends.'],
+        'TOOL_CALL_RESULT' => [:produced, 'Tool result after the host redaction policy.'],
+        'TOOL_CALL_CHUNK' => [:not_produced, 'Convenience form; the gem emits the explicit triad.'],
+        'MESSAGES_SNAPSHOT' => [:host_owned, 'Not produced: history is the host\'s; ids are never re-synthesized.'],
+        'STATE_SNAPSHOT' => [:produced, 'Reconnect: the state the host gave the run, never replayed deltas.'],
+        'STATE_DELTA' => [:host_owned, 'Not produced: patches are the host\'s to describe; the gem invents none.'],
+        'ACTIVITY_SNAPSHOT' => [:not_produced, 'No ACTIVITY_* projection yet; after_tool_progress is not mapped.'],
+        'ACTIVITY_DELTA' => [:not_produced, 'No ACTIVITY_* projection yet; the gem does not invent patches.'],
+        'REASONING_START' => [:not_produced, 'Private reasoning is not emitted until a host opts in.'],
+        'REASONING_MESSAGE_START' => [:not_produced, 'Never emitted; a chunk that carries thinking is ignored.'],
+        'REASONING_MESSAGE_CONTENT' => [:not_produced, 'Never emitted; a chunk that carries thinking is ignored.'],
+        'REASONING_MESSAGE_END' => [:not_produced, 'Never emitted; nothing opens a reasoning block to close.'],
+        'REASONING_MESSAGE_CHUNK' => [:not_produced, 'Convenience form; not emitted.'],
+        'REASONING_END' => [:not_produced, 'Never emitted; nothing opens a reasoning block to close.'],
+        'REASONING_ENCRYPTED_VALUE' => [:not_produced, 'No encrypted reasoning source in RubyLLM 2.x.'],
+        'RAW' => [:not_produced, 'The gem never passes provider payloads through.'],
+        'CUSTOM' => [:optional, 'Only safe, documented host extensions.'],
+        'SUBAGENT_STARTED' => [:not_produced, 'RubyLLM 2.x runs one chat; no subagent data exists.'],
+        'SUBAGENT_FINISHED' => [:not_produced, 'RubyLLM 2.x runs one chat; no subagent data exists.'],
+        'SUBAGENT_ERROR' => [:not_produced, 'RubyLLM 2.x runs one chat; no subagent data exists.']
+      }.freeze
+
+      # The 1.0 shapes `ag-ui-protocol` 0.2.0 cannot express, with the gem's
+      # handling. Upstream issues are drafted in docs/.internal/upstream.
+      GAPS = [
+        {
+          id: 'SDK-GAP-01',
+          shape: 'RunFinishedCancelledOutcome',
+          detail: 'ag-ui-protocol 0.2.0 has success and interrupt outcomes only.',
+          gem_handling: 'RubyLLM::AgUI::Protocol::CancelledOutcome, a schema-valid "cancelled" outcome.',
+          upstream: 'https://github.com/ag-ui-protocol/ag-ui/issues'
+        },
+        {
+          id: 'SDK-GAP-02',
+          shape: 'RUN_STARTED.protocolVersion',
+          detail: "0.2.0's RunStartedEvent has no protocolVersion field.",
+          gem_handling: 'RubyLLM::AgUI::Protocol::RunStartedEvent adds it, defaulting to "1.0".',
+          upstream: 'https://github.com/ag-ui-protocol/ag-ui/issues'
+        },
+        {
+          id: 'SDK-GAP-03',
+          shape: 'JSON to RunAgentInput parser',
+          detail: '0.2.0 models have constructors and to_h only; there is no inbound parser.',
+          gem_handling: 'RubyLLM::AgUI::Input.parse with size and schema bounds.',
+          upstream: 'https://github.com/ag-ui-protocol/ag-ui/issues'
+        },
+        {
+          id: 'SDK-GAP-04',
+          shape: 'SUBAGENT_STARTED / _FINISHED / _ERROR',
+          detail: 'The five legacy THINKING constants are present; the three SUBAGENT types are not.',
+          gem_handling: 'Not produced: RubyLLM 2.x runs a single chat with no subagent data.',
+          upstream: 'https://github.com/ag-ui-protocol/ag-ui/issues'
+        }
+      ].freeze
+
+      # Event types present in the SDK enum but not in the 1.0 schema (the five
+      # legacy THINKING constants). Emitting one would masquerade as 1.0.
+      LEGACY_SDK_ONLY = %w[
+        THINKING_TEXT_MESSAGE_START THINKING_TEXT_MESSAGE_CONTENT THINKING_TEXT_MESSAGE_END
+        THINKING_START THINKING_END
+      ].freeze
+
+      module_function
+
+      # Every schema event type with its family and status, as an array of
+      # hashes suitable for docs generation.
+      def entries
+        SCHEMA_EVENT_TYPES.map do |type|
+          status, note = STATUS.fetch(type)
+          { type: type, family: family_for(type), status: status, note: note }
+        end
+      end
+
+      # The family an event type belongs to.
+      def family_for(type)
+        prefix = FAMILIES.keys.find { |key| type.start_with?(key) }
+        FAMILIES.fetch(prefix)
+      end
+
+      # Event types grouped by status.
+      def report
+        entries.group_by { |entry| entry[:status] }
+      end
+
+      # Event type constants the SDK defines (read at runtime, not hardcoded).
+      def sdk_event_types
+        ::AgUiProtocol::Core::Events::EventType.constants.map { |name| ::AgUiProtocol::Core::Events::EventType.const_get(name) }
+      end
+
+      # SDK constants with no 1.0 schema counterpart.
+      def sdk_only_event_types
+        sdk_event_types - SCHEMA_EVENT_TYPES
+      end
+
+      # 1.0 schema types with no SDK constant.
+      def schema_only_event_types
+        SCHEMA_EVENT_TYPES - sdk_event_types
+      end
+    end
+  end
+end