ruby_llm-ag_ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ab7bc5eeccd9381e134cd795b20b0815aed665ac3f4371d29503bed969811410
+  data.tar.gz: 5991ee6bec49c64e3dd5ac0f8f9ccd18abe7c5f9aab55cb5493b232cff088cbe
+SHA512:
+  metadata.gz: 205524fd5c5cbcd214da1f98c2c2b3678e0961b417ee598803741b577a7c7400be2e51b8d78716905cb14b2fb386d3ee46a8a3e157947cbf06afe6eaf8d01669
+  data.tar.gz: 8680a5a03eacc9cfa8d3920db2be725d5f148befd24125a9b6875312307c4207528f69b527dc294f7e064a2c4f33d0c5bf3666318d3ea81f5927089f6408ae78

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-18
+
+### Added
+
+- Initial gem skeleton: gemspec, Zeitwerk loader, configuration, errors and the
+  `RubyLLM::AgUI` namespace.
+- Inbound `RunAgentInput` parsing with size and schema bounds.
+- RubyLLM 2.x to AG-UI 1.0 mapping for text, tool and lifecycle events, audited
+  against the pinned 1.0 schema (31 event types, see `docs/_reference/protocol-coverage.md`).
+- Run reservation, approval interrupt/resume and the cancelled outcome.
+- An SSE writer and an optional Rails adapter: a controller concern, a durable
+  ActiveRecord run store and an install generator.
+- Reconnect: a re-sent input for a run that already ended gets `RUN_STARTED`, its
+  `STATE_SNAPSHOT` and the recorded terminal event instead of a second run.
+- A runnable pure-Ruby Rack example (`examples/pure_ruby`) that works with no
+  provider, and a Rails 8 endpoint example (`examples/rails_8`).
+- An opt-in live-provider spec (`RUBY_LLM_LIVE=1 bundle exec rspec spec/live`).
+- Documentation: architecture, protocol coverage, compatibility, Rails, security,
+  licenses and upstream `ag-ui-protocol` issue drafts.
+- Versioned GitHub Pages guides and an RDoc API reference.
+- Tag-triggered RubyGems trusted publishing with dependency audits, isolated
+  package installation checks, and GitHub Release assets.
+
+### Fixed
+
+- Register the install generator under `ruby_llm:ag_ui:install` so Rails can
+  resolve the documented command.
+- Require patched CGI, DNS resolution, URI and zlib runtime gems so an isolated
+  install does not activate older vulnerable Ruby default libraries.
+- A second turn on the same chat no longer leaks the previous run's message ids,
+  steps and text into its own stream. RubyLLM's callbacks are additive, so the
+  callbacks a finished run registered stay attached; a mapper is now final after
+  it closes its run.
+- A refused request is answered with the status the error names (413 for a body
+  past the configured limit, not 400).
+- The generated migration targets the host's Rails version instead of a
+  hardcoded `7.1`.
+- The durable store writes the run record as JSON text the gem encodes, so it no
+  longer depends on the host's ActiveSupport JSON encoder (which breaks on
+  Rails 8.0 with `json` 3.x).

data/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thanks for helping. This is an unofficial community gem; small, focused changes
+with tests are the easiest to accept.
+
+## Getting started
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Ground rules
+
+- **Do not fork the AG-UI schema.** Where `ag-ui-protocol` lacks a 1.0 shape,
+  emit a schema-valid event and open an upstream issue before a PR. The known
+  gaps (the JSON input parser, the cancelled outcome, subagent events, the
+  `RUN_STARTED` `protocolVersion`) are tracked in
+  [docs/_reference/protocol-coverage.md](docs/_reference/protocol-coverage.md), with issue drafts in
+  [docs/.internal/upstream/](docs/.internal/upstream).
+- **Never load Rails from the core.** `require 'ruby_llm/ag_ui'` must not load
+  Rails, open a network connection, or read provider credentials. There is a
+  spec that asserts this.
+- **Do not define or reopen top-level `AgUi`.** That namespace is owned by the
+  separate `ag-ui` gem. Inside `RubyLLM::AgUI`, refer to the protocol SDK as
+  `::AgUiProtocol`, and write `::Rails` for the framework.
+- **Do not weaken trust boundaries.** No invented events, no raw exception text
+  or secrets in SSE or logs, and no approval that is not bound to the tool call
+  it approves.
+- Follow the [Semantic Versioning](https://semver.org) policy and add a
+  CHANGELOG entry for user-visible changes.
+
+## Tests
+
+Every behavior change needs a test, and lifecycle, identity and security changes
+need their negative case too. The acceptance IDs (FR-01..FR-08) are referenced
+in spec descriptions. Offline CI uses fakes; live provider tests are opt-in and
+never required:
+
+```bash
+RUBY_LLM_LIVE=1 OPENAI_API_KEY=... bundle exec rspec spec/live
+```
+
+## Commit style
+
+Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:`),
+one coherent change per commit.
+
+## Releasing
+
+Maintainer only. Match `lib/ruby_llm/ag_ui/version.rb` and the documentation
+version, add the version to CHANGELOG, and run the package checks in
+[Releasing](docs/_reference/releasing.md). Push the completed commit and its
+matching `vX.Y.Z` tag. The `Release Gem` workflow verifies the tag, publishes
+through RubyGems trusted publishing, and creates the GitHub Release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Wang and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# ruby_llm-ag_ui
+
+[![CI](https://github.com/yorzi/ruby_llm-ag-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/yorzi/ruby_llm-ag-ui/actions/workflows/ci.yml)
+
+Run [RubyLLM](https://rubyllm.com) 2.x chats as [AG-UI](https://github.com/ag-ui-protocol/ag-ui) 1.0 agent runs.
+
+`ruby_llm-ag_ui` turns one RubyLLM chat turn into one AG-UI run: it validates the
+inbound `RunAgentInput`, maps RubyLLM streaming, tool and lifecycle behavior onto
+schema-valid AG-UI events, turns `requires_approval` pauses into interrupt
+outcomes with host-authorized resume, reports `Chat#cancel` as the cancelled
+outcome, and writes the stream as Server-Sent Events. A pure-Ruby core comes
+with an optional Rails adapter.
+
+> **Unofficial community project.** This gem is not affiliated with, endorsed
+> by, or maintained by the RubyLLM maintainers or the AG-UI protocol
+> maintainers. `RubyLLM::` and "AG-UI" appear here because this gem extends
+> those projects, not because it speaks for them.
+
+## Why
+
+If your agent already runs on RubyLLM and you want an AG-UI client (CopilotKit,
+`@ag-ui/client`, or another AG-UI consumer) in front of it, you currently have
+to hand-map RubyLLM callbacks, approval pauses and cancellation onto the AG-UI
+run lifecycle, and you have to parse and authorize `RunAgentInput` yourself:
+the community Ruby SDK builds outbound events but has no inbound parser. The
+usual results are wrong terminal events, duplicate runs on retry, approvals that
+are not bound to the call they approve, and cancellations reported as success.
+This gem removes that mapping work.
+
+## What it does and does not do
+
+It owns the RubyLLM → AG-UI mapping, input parsing, event ordering, run identity
+and terminal correctness. It is **not** an AG-UI core SDK, a schema fork, a chat
+UI, a CopilotKit runtime clone, or a second agent framework. RubyLLM owns the
+agent loop, tool execution, approval pauses and cancellation checkpoints. Your
+application owns identity, authorization, which tools and model a run may use,
+and persistence.
+
+## Status
+
+Version `0.1.0` is the first release. The pure-Ruby core, run store, approval/resume, cancel
+handling and the Rails adapter are implemented and covered by an offline test
+suite. Compatibility claims for real AG-UI clients and live providers are
+tracked in the [compatibility guide](https://rubyllm-ag-ui.wangyaodi.com/compatibility/) and are
+**not** asserted until recorded there.
+
+Read the [documentation site](https://rubyllm-ag-ui.wangyaodi.com/) for the
+guides, protocol coverage, compatibility matrix and security model. Its source
+is in [docs/](https://github.com/yorzi/ruby_llm-ag-ui/tree/main/docs).
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'ruby_llm-ag_ui', '~> 0.1.0'
+```
+
+```bash
+bundle install
+```
+
+Requires Ruby >= 3.2, RubyLLM >= 2.1 and `ag-ui-protocol` ~> 0.2.0.
+Runtime dependencies also select patched `cgi`, `resolv`, `uri` and `zlib` gems.
+
+## Quick start (pure Ruby)
+
+The host authenticates, authorizes and builds the chat; the gem writes the
+stream.
+
+```ruby
+require 'ruby_llm'
+require 'ruby_llm/ag_ui'
+
+input = RubyLLM::AgUI::Input.parse(request_body)   # bounds, validates, digests
+chat  = host_chat_for(actor, input.thread_id)     # your RubyLLM::Chat
+
+RubyLLM::AgUI::Run.new(
+  chat: chat,
+  input: input,
+  scope: "tenant:#{tenant.id}:actor:#{actor.id}", # from authenticated identity
+  store: run_store
+).stream(to: sse_io)
+```
+
+`scope` is what the run is reserved under: it must be a non-empty String the host
+builds from authenticated identity, never anything from the request body.
+
+`examples/pure_ruby/app.rb` is a runnable Rack endpoint that streams a complete
+run (a tool call, an approval pause and the run that answers it) with no
+provider and no credentials (`rake example`, or
+`rackup examples/pure_ruby/config.ru`). Set `RUBY_LLM_AG_UI_EXAMPLE_MODEL` to
+drive a real `RubyLLM::Chat` through the same code.
+
+## Rails
+
+The optional adapter provides a controller concern, a durable run store keyed
+by the actor's scope, and reconnect snapshots. It loads only when
+`Rails::Railtie` is already defined.
+
+```ruby
+class AgentRunsController < ApplicationController
+  include RubyLLM::AgUI::Rails::Streaming
+
+  def create
+    stream_ag_ui_run { |input| current_user.chats.find_or_create_by!(ag_ui_thread_id: input.thread_id) }
+  end
+
+  def ag_ui_scope
+    "actor:#{current_user.id}"
+  end
+end
+```
+
+See the [Rails integration guide](https://rubyllm-ag-ui.wangyaodi.com/rails-integration/) and `examples/rails_8`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+rake example        # prints a full AG-UI run as SSE
+```
+
+The suite is offline: fakes instead of a provider, no network, no credentials.
+The only test that talks to a model is opt-in:
+
+```bash
+RUBY_LLM_LIVE=1 OPENAI_API_KEY=... bundle exec rspec spec/live
+```
+
+## Documentation
+
+- [Architecture](https://rubyllm-ag-ui.wangyaodi.com/overview/) - the components, run, and invariants.
+- [Protocol coverage](https://rubyllm-ag-ui.wangyaodi.com/protocol-coverage/) - all 31 AG-UI 1.0 event types
+  and what this gem does with each.
+- [Compatibility](https://rubyllm-ag-ui.wangyaodi.com/compatibility/) - what this repository verifies.
+- [Rails](https://rubyllm-ag-ui.wangyaodi.com/rails-integration/) - the controller concern, store, and transport.
+- [Security](https://rubyllm-ag-ui.wangyaodi.com/security-and-deployment/) - the threat model and deployment checklist.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt). Read the [third-party notices](https://rubyllm-ag-ui.wangyaodi.com/third-party-notices/).
+
+This is an unofficial community project and is not affiliated with the RubyLLM or
+AG-UI maintainers. Report security issues privately. See [SECURITY.md](SECURITY.md).

data/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Supported versions
+
+The latest released minor version receives security fixes.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a security problem. Use GitHub's private
+vulnerability reporting on the repository
+(<https://github.com/yorzi/ruby_llm-ag_ui/security/advisories/new>) or email the
+maintainer at <andy@yorzi.me>.
+
+Include, where possible:
+
+- the affected version and Ruby/RubyLLM/`ag-ui-protocol` versions;
+- a minimal reproduction, ideally without real credentials or model calls;
+- whether untrusted input, an approval bypass, a duplicated side effect, or a
+  leak into SSE or logs is involved.
+
+You will get an acknowledgement within 7 days. Credit is offered unless you
+prefer to stay anonymous.
+
+## Security model
+
+The threat model is documented in the [security and deployment guide](https://rubyllm-ag-ui.wangyaodi.com/security-and-deployment/). In
+short: client-supplied `messages`, `state`, `tools`, `context` and
+`forwardedProps` are untrusted and never grant host privileges or change host
+policy; tool approvals and `resume` payloads are never permission grants; and
+`RUN_ERROR` carries a sanitized message and code, never raw exception text.

data/docs/_advanced/rails-integration.md

@@ -0,0 +1,199 @@
+---
+layout: default
+title: "Rails Integration"
+nav_order: 1
+description: Serve AG-UI runs from Rails with the optional controller concern and durable ActiveRecord store.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to install the Rails adapter files.
+* How to authenticate, select a chat, and stream a run.
+* What the durable store and reconnect path provide.
+
+The adapter is optional. It is what a Rails host gets for free: a controller
+concern that serves the event stream, a durable run store backed by ActiveRecord,
+a generator for both, and reconnect support.
+
+Nothing under `lib/ruby_llm/ag_ui/rails/` loads unless `Rails::Railtie` is already
+defined, so a pure-Ruby app pays nothing for it.
+
+## Install
+
+```bash
+bundle add ruby_llm-ag_ui
+bin/rails generate ruby_llm:ag_ui:install
+bin/rails db:migrate
+```
+
+The generator writes two files:
+
+- `db/migrate/*_create_ruby_llm_ag_ui_runs.rb`: one row per run, with a unique
+  index on `(scope, thread_id, run_id)` and one on
+  `(scope, thread_id, status)`.
+- `config/initializers/ruby_llm_ag_ui.rb`: points `config.run_store` at
+  `RubyLLM::AgUI::Rails::ActiveRecordStore` and lists the choices worth making.
+
+The migration targets the host's own Rails version
+(`ActiveRecord::Migration.current_version`), so it does not pin a schema version
+you did not choose.
+
+## The controller
+
+```ruby
+class AgentRunsController < ApplicationController
+  include RubyLLM::AgUI::Rails::Streaming
+
+  def create
+    stream_ag_ui_run { |input| chat_for(input) }
+  end
+end
+```
+
+`stream_ag_ui_run` parses the body, resolves the chat, runs, and writes SSE. The
+block receives the parsed `Input` and must return the chat for it.
+
+Two methods are yours:
+
+```ruby
+# Required. Built from the authenticated request, never from the input.
+def ag_ui_scope
+  "tenant:#{current_tenant.id}:actor:#{current_user.id}"
+end
+
+# Optional. The state to publish on a reconnect, or nil (the default).
+def ag_ui_state
+  { 'orders' => current_user.visible_orders.map(&:as_json) }
+end
+```
+
+`ag_ui_scope` has no default on purpose: raising a `ConfigurationError` is better
+than quietly reserving every run under one shared scope. It bounds every store
+lookup, so two actors using the same `threadId` cannot reach each other's runs.
+
+`ag_ui_state` is only published when a completed run is served to a client that
+reconnects. It is not replayed as deltas, and the gem never computes it; your
+app knows what the client is looking at.
+
+## What the client gets, and when
+
+| Request | Response |
+|---|---|
+| Valid input, `Accept: text/event-stream` | `200`, SSE, one `data:` line per AG-UI event |
+| `Accept` that cannot read SSE | `406` before any event |
+| Empty, non-JSON, or schema-invalid body | `400` |
+| Body past `config.max_input_bytes` | `413` |
+| `threadId` the actor does not own, when the block raises `ActiveRecord::RecordNotFound` | `404` |
+| Same `(scope, threadId, runId)` with different input | `409` |
+| A live run that already has a stream | `409` |
+| The same identity and input for a run that ended | `200`, `RUN_STARTED` + `STATE_SNAPSHOT` + the recorded terminal event |
+| Client disconnects mid-run | no error; the record in the store is the outcome |
+
+Refusals are decided before the response commits, so a client that cannot be
+served gets a status code instead of a stream that stops mid-event. A disconnect
+is not a run outcome: the run keeps its own record, and a reconnect server can
+serve it.
+
+## The store
+
+`Rails::ActiveRecordStore` implements the same contract as `MemoryStore` and is
+what makes run identity survive a worker:
+
+- `reserve` inserts; a `RecordNotUnique` means another worker won, and the
+  existing row is attached or refused by digest.
+- `redeem_interrupt` runs under `row.with_lock`, so exactly one resume records a
+  decision and the tool runs once.
+- `find_interrupt` is scoped by `(scope, thread_id, interrupt_id)`, so an
+  interrupt id is not a global key.
+
+`scope`, `thread_id` and `run_id` are strings; the record itself is stored as
+JSON **text** in `payload`, because a record is immutable and has no partial
+update to model. The gem does the encoding, so the stored shape is exactly
+`RunRecord#to_storage` on every database and Rails version, rather than whatever
+the host's ActiveSupport JSON encoder produces.
+
+Use `MemoryStore` only for a single process (development, tests, one Puma worker
+with no restarts). It is per-process, and a retry after a restart is a new run.
+
+## Resume, from the client's side
+
+A pause is a `RUN_FINISHED` with an interrupt outcome:
+
+```json
+{"type":"RUN_FINISHED","threadId":"thread-1","runId":"run-1",
+ "outcome":{"type":"interrupt","interrupts":[
+   {"id":"9f2c...","reason":"tool_call_confirmation",
+    "message":"Approve the cancel_order tool call?",
+    "toolCallId":"call_1","expiresAt":"2026-10-18T12:15:00Z"}]}}
+```
+
+The client answers it on a **new run** for the same thread:
+
+```json
+{"threadId":"thread-1","runId":"run-2",
+ "messages":[{"id":"m1","role":"user","content":"Cancel order 42."}],
+ "resume":[{"interruptId":"9f2c...","status":"resolved"}]}
+```
+
+`status: "cancelled"` records a denial instead. Either way the interrupt must
+still be pending, unexpired, and bound to the same tool call arguments the host
+chat holds, or the run is refused before it is reserved.
+
+The approval is a request, not a permission: re-authorize before the tool runs.
+
+## Transport
+
+`ActionController::Live` holds a thread for the life of the run and is the
+simplest thing that streams correctly. Before production, know its two costs:
+
+- **Threads.** A server with `N` workers and `T` threads can serve `T` concurrent
+  streams. Long model calls make that a real limit.
+- **Proxies.** `X-Accel-Buffering: no` is set for nginx, but any intermediary that
+  buffers will turn the stream into one response at the end. `curl -N` is the
+  quickest way to see whether yours does.
+
+If you need to survive deploys, or to serve one run to several clients, run the
+work elsewhere and have the controller read from your own broker. The gem gives
+you the parts, not the relay: any object with `#write` is a stream, the run record
+is durable, and `RubyLLM::AgUI::Reconnect` builds the events for a run that has
+already ended. Two live streams for one run are refused rather than merged,
+because a silent second stream duplicates the work.
+
+## Testing a host app
+
+The adapter's own specs live in `spec/rails_helper.rb`-based files and are not
+auto-required. In your app, two kinds of test are usually enough:
+
+1. A controller test that the refusals happen (no auth, wrong `Accept`, a
+   `threadId` the actor does not own) and that a valid request yields an event
+   stream.
+2. A store test that the same identity twice does not execute twice, and that a
+   resume replayed twice does not run the tool twice.
+
+You do not need a real model for either: pass a chat double that plays
+`before_tool_call`, `after_message`, `complete`, `waiting?`,
+`awaiting_approval?`, `pending_approvals`, `approve` and `deny`, which is exactly
+what `spec/support/fake_chat.rb` in this repository does.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| The whole response arrives at once | A buffering proxy, or `curl` without `-N` |
+| `406` for every request | The client did not send `Accept: text/event-stream` |
+| `ConfigurationError` about `ag_ui_scope` | The controller does not define it |
+| `409` on a request the client thinks is new | The same `(scope, threadId, runId)` was used with different input |
+| `409` on a second tab of the same run | A live run has one stream; serve the second client from your own relay |
+| Tool results are `[redacted]` | Redaction is the default; configure `config.redact` |
+| A run succeeds but the client shows nothing | The client was not sent the interrupt/resume flow it expected, or it re-sent a `runId` whose run had already ended |
+
+## Next Steps
+
+* [Approval and Resume]({% link _core_features/approval-and-resume.md %}) - answer a tool approval pause.
+* [Reconnects and Run Identity]({% link _core_features/reconnects.md %}) - understand durable run records.
+* [Security and Deployment]({% link _advanced/security-and-deployment.md %}) - review host authorization duties.