ruby_llm-ag_ui 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd1d89205c88b89562445e5f654f2f2f931753ac4ff4e2ed4434031ad65251d6
-  data.tar.gz: ec70b5e27313a50c8596beaa33c2de9f3b8fc46fab5968b309cc8f626b4a70a0
+  metadata.gz: 7e2fef2885431f82e496f0e1682bbd6d11ed036a6dcda941353e5f70d22e9589
+  data.tar.gz: 06d1631a5e98ecfea25a53dd9ea9f40c235f2fea871fcc7d4fb9e2b707596439
 SHA512:
-  metadata.gz: 7526b6e10f776726e8647efa1a47819d4958b0f0e54cb57f65c81968c4929bbf7330a326197adcbc869f1cc3333921d37f8eb74eb088da9f71690cea7a2c6715
-  data.tar.gz: ec8fd2a7271e5aa28f8084716a75ebd8d5067a2d7d4e164aa521e8ceeea4b24897397242f1110ef0cd6cd4b5588dd0fb7c25e732c137ea196c5249ef5ece7f28
+  metadata.gz: bc183b5b76a8f3f92a27feb731a879780b454425a95c024bfc5ebba2c23f006ec2da5c2682c1c2074dcb4a946650d3941aa0482915c3987873c5bcc420613f3e
+  data.tar.gz: 19da3e02abe3806802bbe4efee68138a3a8b7e31477ae43a7085511f748dd88df59c71ba12398bf84310a74c7e57fca8ee25581e26d9ce797816ca95f5b5f3db

data/CHANGELOG.md

@@ -6,6 +6,33 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-21
+
+### Added
+
+- A proposed public application and custom-store contract, with orchestration
+  internals excluded from generated API documentation.
+- Explicit RubyLLM 2.1.0 and 2.1.1 CI matrices, and a shared intercepted/live
+  OpenRouter harness for text, approval, result association, and reconnect.
+- Client-state assertions for one original tool call and one associated result.
+
+### Changed
+
+- Remove the unused `allow_client_history` configuration and diagnostic key.
+  Client messages remain untrusted data under host-controlled history policy.
+- Reject unsupported `protocol_version` configuration instead of accepting a
+  setting that cannot change the producer's fixed 1.0 output.
+
+### Fixed
+
+- Expose the returned reconnect outcome through `Run#record`, without executing
+  the chat again. Verify real RubyLLM denial and installed result association.
+- Resume real RubyLLM approval without repeating the original tool-call start
+  and arguments. Its result keeps the original call id; new calls still stream.
+- Isolate and freeze nested input, identity, interrupt, and JSON record values.
+  Editing caller-owned data cannot mutate memory-store indexes or bypass a
+  record revision; editing published values raises `FrozenError`.
+
 ## [0.3.0] - 2026-10-20
 
 ### Added

data/README.md

@@ -19,7 +19,7 @@ RubyLLM and AG-UI maintainers.
 ## Install
 
 ```ruby
-gem 'ruby_llm-ag_ui', '~> 0.3.0'
+gem 'ruby_llm-ag_ui', '~> 0.4.0'
 ```
 
 Requires Ruby >= 3.2, RubyLLM >= 2.1 and < 3.0, and `ag-ui-protocol` 0.2.x.

data/docs/_advanced/provider-verification.md

@@ -0,0 +1,70 @@
+---
+layout: default
+title: Provider Verification
+nav_order: 6
+description: Run opt-in provider checks separately from offline client and protocol tests.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to run the maintained live checks with synthetic input.
+* What the checks verify and which calls can reach a provider.
+* How to keep credentials and provider results out of shared evidence.
+
+## Run the Opt-in Checks
+
+From the repository, with `OPENROUTER_API_KEY` already configured:
+
+```sh
+RUBY_LLM_LIVE=1 bundle exec rspec spec/live
+```
+
+The harness uses OpenRouter with `openai/gpt-4.1-mini`. Set
+`RUBY_LLM_LIVE_MODEL` to choose another OpenRouter model; record its name and
+result separately. A successful model does not verify every model on the gateway.
+These calls can incur provider charges. Default offline tests never run them.
+
+If you use an environment file, keep it untracked and load it through dotenv:
+
+```sh
+RUBY_LLM_LIVE=1 bundle exec dotenv -f .env.live rspec spec/live
+```
+
+Set the key in that file or your existing credential manager. Do not put keys
+in command arguments, inline exports, screenshots, or committed fixtures.
+The repository ignores `.env*` files except `.env.example`.
+
+## Understand the Checks
+
+One example streams a short text response. Another forces a synthetic lookup
+that requires approval, verifies no tool execution before approval, resumes the
+original call, and reconnects the completed resume. The tool only returns a
+fixture value; it does not access a database, file, or business service.
+Its result is redacted and retains the original tool-call id.
+
+The provider configuration disables retries, caps output at 128 tokens, uses
+a 30-second request timeout, and discards provider logs. The live network
+allowlist permits only the OpenRouter HTTPS chat-completions endpoint. This
+allowlist is a test guard, not an operating-system firewall.
+
+An offline test drives the same setup through intercepted HTTP. It verifies
+the bounded request and reproduces the real RubyLLM approval callbacks without
+credentials. Browser tests continue to use the maintained synthetic host; they
+verify the official client's message and tool-result association separately.
+
+## Record Evidence Without Secrets
+
+Record the date, Ruby and RubyLLM versions, provider route, model, pass/fail
+result, and any fixed regression. Keep generated evidence under ignored `tmp/`.
+Do not save raw HTTP headers or provider traces. A failed assertion, intercepted
+request, or schema-valid event is not proof that a live request completed.
+
+For the recorded results and unverified paths, read
+[Compatibility]({% link _reference/compatibility.md %}). Live cancellation,
+timeouts, and network-loss timing require separate provider evidence; offline
+fault injection does not establish those provider behaviors.

data/docs/_advanced/security-and-deployment.md

@@ -43,8 +43,8 @@ responsibility.
 - **Choose the model, tools or system prompt.** `input.tools` is informational:
   `Input#tool_names` and `Input#client_tools?` report it, and nothing in the gem
   registers a client-supplied tool on the chat. `input.messages` is parsed and
-  echoed, never appended to the chat as trusted turns; `config.allow_client_history`
-  is off and documented as off.
+  echoed, never appended to the chat as trusted turns. The host owns history
+  reconciliation; this gem has no switch that imports client history.
 - **Reach another actor's run.** Every lookup is bounded by the scope the host
   supplies. The same `(threadId, runId)` under a different scope is a different
   run (`spec/ruby_llm/ag_ui/run_spec.rb`: "does not let one scope attach to

data/docs/_core_features/approval-and-resume.md

@@ -60,3 +60,12 @@ The interrupt must still be pending and unexpired. The tool call id and argument
 * [Streaming Runs]({% link _core_features/streaming-runs.md %}) - follow the event and outcome sequence.
 * [Reconnects and Run Identity]({% link _core_features/reconnects.md %}) - understand stored run identity.
 * [Security and Deployment]({% link _advanced/security-and-deployment.md %}) - keep approval separate from authorization.
+
+
+## Keep the Original Tool Call
+
+RubyLLM fires its before-tool callback when an approved call executes. The
+resume run does not repeat the original `TOOL_CALL_START`, arguments, or end.
+Its `TOOL_CALL_RESULT` uses the original `toolCallId`. A later new tool call
+still emits its own start and arguments. Keep the client conversation across
+both runs so the result can attach to the call shown before the interrupt.

data/docs/_core_features/reconnects.md

@@ -52,3 +52,18 @@ stuck record; deleting its reservation can repeat unknown tool effects.
 * [Configuration]({% link _getting_started/configuration.md %}) - set the default store.
 * [Rails Integration]({% link _advanced/rails-integration.md %}) - install the durable ActiveRecord store.
 * [Protocol Coverage]({% link _reference/protocol-coverage.md %}) - inspect reconnect events.
+
+
+## Keep Request and Record Values Read-only
+
+Parsed input, run identity, and JSON snapshots are isolated from the objects
+supplied by the caller. Nested strings, arrays, hashes, and parsed SDK message
+models are frozen. Editing them raises `FrozenError`; it cannot change the
+reserved digest or bypass a store revision check. Constructors copy JSON values
+rather than freezing the host's original state. Keep snapshots JSON-compatible.
+
+Create a new input with `Input.parse` for a new request. Use `RunRecord`
+transitions and retain `store.save`'s returned record when updating storage.
+
+After `Run#stream` returns a recorded outcome, `Run#record` exposes that same
+record, including on a reconnect. Reading it never executes the chat.

data/docs/_getting_started/configuration.md

@@ -40,14 +40,19 @@ The global configuration supplies defaults. `Run.new` can override the store, lo
 | `redact` | `Redaction.default` | Transform tool results before they reach the stream. |
 | `emit_tool_progress` | `false` | Publish tool progress as redacted activity snapshots. |
 | `logger` | `nil` | Receive host-side diagnostics without prompts or raw tool payloads. |
-| `protocol_version` | `"1.0"` | Value reported by `RUN_STARTED`. |
+| `protocol_version` | `"1.0"` | Fixed supported version reported by `RUN_STARTED`; setting another value raises `ConfigurationError`. |
 | `max_input_bytes` | `256_000` | Maximum request body size. |
 | `max_messages` | `500` | Maximum messages in one request. |
 | `max_tools` | `64` | Maximum tool definitions in one request. |
 | `max_context` | `64` | Maximum context entries in one request. |
 | `interrupt_ttl` | `900` seconds | How long an approval interrupt can be answered. |
 | `clock` | `Time.now.utc` | Clock used to set interrupt expiry. |
-| `allow_client_history` | `false` | Reserved for future history behavior; client history is not trusted in this release. |
+
+`Configuration#protocol_version=` accepts only `"1.0"`. Its value describes the
+producer; it does not select another event schema.
+
+Client history stays under host control. There is no configuration switch that
+trusts or imports it into a chat.
 
 Provider keys and model selection are configured through RubyLLM and the host app. This gem does not read credentials when it loads.
 

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

@@ -0,0 +1,57 @@
+---
+layout: default
+title: "What's New in 0.4"
+nav_order: -1
+description: Review the public integration contract and verified compatibility boundaries.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* Which configuration changes need an application update.
+* Where to find the proposed public API and compatibility evidence.
+
+## Use Effective Configuration
+
+```ruby
+RubyLLM::AgUI.configure do |config|
+  config.protocol_version = '1.0'
+end
+```
+
+Other protocol versions raise `ConfigurationError`. The unused
+`allow_client_history` setting is removed. Client history remains the host's
+responsibility. See [Upgrading]({% link _reference/upgrading.md %}).
+
+## Preserve Immutable Request and Store Values
+
+Parsed input and JSON record values now copy and freeze their nested members.
+Changing a caller's original state cannot change a stored snapshot or identity.
+Use new inputs and record transitions instead of editing nested values. See
+[Reconnects]({% link _core_features/reconnects.md %}).
+
+The [Public API Contract]({% link _reference/public-api.md %}) identifies
+application and custom-store APIs and separates orchestration internals.
+
+## Associate Resumed Tool Results Once
+
+Real RubyLLM approval resumes now emit the result of the original call without
+repeating its start and arguments. The offline real-chat and opt-in provider
+checks use the same harness. `Run#record` also exposes the recorded outcome
+after a reconnect, matching the return value from `stream`. See
+[Approval and Resume]({% link _core_features/approval-and-resume.md %}).
+
+## Verify the Provider Separately
+
+The opt-in harness checks OpenRouter text and a synthetic approval/resume
+without external business effects. The same real RubyLLM chat setup has offline
+HTTP tests. See [Provider Verification]({% link _advanced/provider-verification.md %})
+for credential handling, request limits, and the scope of the results.
+
+Read
+[Compatibility]({% link _reference/compatibility.md %}) for recorded results
+and limits; an intended matrix is not a completed verification.

data/docs/_reference/api-reference.md

@@ -11,7 +11,8 @@ description: Browse RDoc pages generated from classes and methods in the gem sou
 {{ 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/`.
+Read the [Public API Contract]({% link _reference/public-api.md %}) before
+depending on a class. The [API reference]({{ '/api/' | relative_url }}) opens on the `RubyLLM` module. The generated pages follow the RDoc comments in `lib/`.
 
 | Build with | Reference |
 | --- | --- |

data/docs/_reference/compatibility.md

@@ -23,11 +23,11 @@ dependency does.
 
 | Component | Range | Evidence |
 |---|---|---|
-| Ruby | `>= 3.2` | Recorded 0.3 CI passes on 3.2.11, 3.3.12, and 3.4.11 |
-| RubyLLM | `>= 2.1`, `< 3.0` | 2.1.1 (callback, approval and cancellation behavior read from its source) |
+| Ruby | `>= 3.2` | Recorded 0.4 CI passes on 3.2.11, 3.3.12, and 3.4.11 |
+| RubyLLM | `>= 2.1`, `< 3.0` | 2.1.0 and 2.1.1 pass the 0.4 CI matrix; the recorded live session uses 2.1.1 |
 | `ag-ui-protocol` | `~> 0.2.0` | 0.2.0 |
 | JSON | `>= 2.0`, `< 3` | 2.21.2 passes both Rails lines; JSON 3 removes the `quirks_mode` option used by Rails 8.0 |
-| Rails (adapter only) | `railties`, `actionpack`, `activerecord` `>= 8.0` | Recorded 0.3 CI passes on 8.0.5.1 and 8.1.4 with Ruby 3.3/3.4 |
+| Rails (adapter only) | `railties`, `actionpack`, `activerecord` `>= 8.0` | Recorded 0.4 CI passes on 8.0.5.1 and 8.1.4 with Ruby 3.3/3.4 |
 | AG-UI schema | pinned commit `89cedd3fd549feeee41e50e1d7c6d373e549241a` | vendored, SHA-256 recorded in [AG-UI Protocol Coverage]({% link _reference/protocol-coverage.md %}) |
 
 The pure-Ruby core uses `ruby_llm` and `ag-ui-protocol`, plus the patched
@@ -54,6 +54,66 @@ adapter is only loaded when `Rails::Railtie` is already defined.
 
 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.
 
+## 0.4 Release Acceptance
+
+The [2026-10-21 acceptance CI](https://github.com/yorzi/ruby_llm-ag-ui/actions/runs/39518735488)
+passes all 17 jobs at `e09b81b`. Each test job reports 296 examples, zero failures,
+and two opt-in provider skips across the Ruby, Rails, and RubyLLM matrix below.
+Local checks also pass 296 examples and lint on 95 files. Both installed
+endpoints verify one original tool call and one result with its original id.
+
+The added regressions cover `Run#record` on reconnect and real RubyLLM denial
+without tool execution. Denial uses intercepted HTTP. The local OpenRouter
+text and approval/resume examples are separately rerun on the release code:
+two live cases plus one offline harness example pass with zero failures.
+
+The browser suite again passes 18 workflows and validates all 242 consumed
+events. Desktop approval progress and 390px mobile denial screenshots were
+inspected. The earlier candidate record below retains its own commit and counts.
+
+## Local 0.4 Development Verification
+
+On 2026-10-21, the candidate passes 294 offline examples with zero failures
+and two opt-in provider checks skipped. Separate runs use RubyLLM 2.1.0 and
+2.1.1 on Ruby 3.3.5 with Rails 8.1.4 and JSON 2.21.2. The [0.4 candidate CI](https://github.com/yorzi/ruby_llm-ag-ui/actions/runs/39515383346)
+passes all 17 jobs at `14b3c15`: six Ruby jobs across 3.2.11, 3.3.12, and
+3.4.11 with both RubyLLM versions; eight Rails jobs across 8.0.5.1 and 8.1.4
+on Ruby 3.3/3.4 with both versions; lint, installed-host, and browser checks.
+Each suite reports 294 examples, zero failures, and two opt-in provider skips.
+
+The maintained client passes 18 workflows and validates all 242 consumed
+events. Approval assertions inspect the official client's messages as well as
+the wire: one original call, one associated result, no duplicate visible text
+after reconnect. The remote browser uses Chromium 156.0.8078.4; local and remote
+desktop progress and 390px denial screenshots were inspected. The fixture now fires the same resumed before-tool callback
+as a real RubyLLM chat. Installed-host and generated Rails model checks pass. A fixed local 66-file
+artifact independently passes clean core loading, activated dependency audit,
+and Rails generator migration up/down. The isolated core uses JSON 2.7.1.
+The root and activated-core audit reports no findings against the recorded
+advisory database. These are development artifact checks, not public downloads.
+
+### Recorded Live Provider Session
+
+The 2026-10-21 local session uses OpenRouter with `openai/gpt-4.1-mini`,
+RubyLLM 2.1.1, and Ruby 3.3.5. Both live examples pass: streamed text, then a
+synthetic tool approval/resume with its original call id, redaction, and completed
+resume reconnect. The tool is not executed before approval and executes once
+after it. The same command includes one offline harness example, for three
+examples total with zero failures. It verifies the gem's Ruby path, not a live
+provider session through the browser or a deployed Rails application.
+
+This session first exposed duplicate tool-call starts on a real resume.
+An intercepted-HTTP real-chat test reproduces that defect before the fix and
+passes afterward. Text, tool results, and approval are live evidence for this
+route and model only. Live cancellation, timeout timing, network loss, denial,
+and other providers remain unverified. Follow
+[Provider Verification]({% link _advanced/provider-verification.md %}) to reproduce.
+
+The checked current `ag-ui-protocol` remains 0.2.0. Its missing cancelled
+outcome and `RUN_STARTED.protocolVersion` still require the local protocol
+shims. Their encoded events pass the pinned schema checks; no workaround is
+removed solely because a new version was expected.
+
 ## Local 0.3 Development Verification
 
 On 2026-10-19, Ruby 3.3.5, RubyLLM 2.1.1, and Rails 8.1.4 pass 284 examples
@@ -89,6 +149,14 @@ chat. Version 0.3 bounds JSON to 2.x; the passing matrix uses 2.21.2. Intercepte
 HTTP tests reproduce the failure before the bound and pass after it. These
 checks make no live provider call.
 
+The [0.3.0 release workflow](https://github.com/yorzi/ruby_llm-ag-ui/actions/runs/39376258843)
+passes offline tests, browser workflows, advisory checks, and installed-host
+plus clean core/Rails checks. After publication, the actual GitHub and RubyGems
+downloads have matching SHA-256 hashes and all 62 packaged files match the tag.
+The downloaded artifact independently passes both installed endpoints and fresh
+core, advisory, and Rails generator migration checks. The isolated macOS core
+activates JSON 2.7.1; the remote test matrix uses 2.21.2.
+
 ## Recorded 0.2 Client Verification
 
 On 2026-10-19, the local 0.2.0 candidate passes the maintained browser workflows
@@ -126,12 +194,12 @@ checks after download.
 - **Other clients or versions.** CopilotKit and client versions other than the
   recorded `@ag-ui/client` version have not been verified. Schema conformance
   does not establish that every UI renders the events correctly.
-- **Live providers.** `spec/live/live_run_spec.rb` is the opt-in check
-  (`RUBY_LLM_LIVE=1`, plus a provider key); its provider context is skipped in the default suite. The same run setup
-  is exercised separately with an offline chat. Provider behavior in 2.1.1 is derived from its source, not from a recorded
-  session.
+- **Other live paths.** Only the recorded OpenRouter model's text and approval
+  workflow is verified live. Browser provider sessions, other providers,
+  cancellation timing, timeouts, and network-loss recovery need separate evidence.
 - **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.
+  is a dependency resolver bound; verified versions are 2.1.0 and 2.1.1. Future
+  2.x releases need the same checks before a compatibility claim.
 - **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.

data/docs/_reference/public-api.md

@@ -0,0 +1,102 @@
+---
+layout: default
+title: Public API Contract
+nav_order: 3
+description: Build against the application API and custom-store contract proposed for 1.0.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* Which entry points applications can depend on.
+* Which values and failures cross the integration boundary.
+* How to implement a custom store without depending on orchestration internals.
+
+## Run One Authorized Turn
+
+```ruby
+input = RubyLLM::AgUI::Input.parse(request_body)
+record = RubyLLM::AgUI::Run.new(
+  chat: host_chat, input: input, scope: authenticated_scope, store: run_store
+).stream(to: response_stream)
+record.status
+```
+
+The host owns its chat, authentication, authorization, history, model, and tools.
+Parsing client data never adds messages or tools to that chat. A completed run
+returns its stored outcome on an exact retry; it never repeats the turn.
+An active duplicate is refused. See
+[Reconnects]({% link _core_features/reconnects.md %}).
+
+Version 0.4 proposes the following application contract for 1.0. It is not a
+1.0 stability promise yet. Breaking changes before 1.0 have upgrade steps.
+
+| Entry point | Application contract |
+| --- | --- |
+| `RubyLLM::AgUI.configure`, `.config`, `.reset_configuration!` | Application defaults listed in [Configuration]({% link _getting_started/configuration.md %}). |
+| `Input.parse(raw, max_bytes: nil, strict: false, logger: nil)` | Accept a Hash, JSON String, or readable body; return parsed identity, data, digest, warnings, and `to_h`. |
+| `Run.new(...).stream(to:)` | Reserve before execution; return a `RunRecord`; serialize callbacks and detach a failed transport. `Run#record` exposes the reserved record and, after completion or reconnect, the returned outcome. |
+| `SSEWriter#write`, `#flush`, `#close`, `#closed?`, `.headers` | Encode schema-valid events on an IO-like stream; direct write failures raise `TransportError`. |
+| `RunRecord`, `Interrupt`, `ResumeEntry` | Read-only identity and JSON data, predicates, documented transitions, and serialization. Transitions return new values. |
+| `Redaction.default`, `.none` and a host callable | Transform tool output and opt-in progress; nil uses the default redactor. |
+| `Coverage` | Inspect produced and unsupported event types for the pinned schema. |
+
+`Mapper` is an advanced event projection API. Its documented methods accept
+RubyLLM chunks, messages, and tool calls; they return events and do not persist
+or execute work. Prefer `Run` when you need identity and terminal guarantees.
+The protocol shim's concrete model classes and constructors are implementation
+details. Depend on encoded AG-UI events, not on a shim class name.
+
+## Implement a Store
+
+Implement the public methods on `Store::Base`: `reserve`, `find`, `latest_run`,
+`latest_interrupted`, `save`, `find_interrupt`, and `redeem_interrupt`.
+`recover` is supplied by the base class, or you can implement the same conditional
+contract. Return `Reservation` and `Redemption` values where the interface
+requires them. Their constructors and predicates are extension API.
+
+Keep scope and run identity isolated. Reserve identities and redeem approvals
+atomically. `save(record)` compares the observed revision and returns a new
+record with a higher revision. Retain the return value. A stale write raises
+`StaleRecordError`. A recovery never supersedes a terminal or newer outcome.
+Read [Worker Recovery]({% link _advanced/worker-recovery.md %}) before using it.
+
+Use `MemoryStore` within one process, or `Rails::ActiveRecordStore` with the
+shipped migration. The verified database is SQLite. Other databases require
+independent concurrency evidence.
+
+## Handle Errors at the Right Boundary
+
+`InputError#http_status` is 400 for malformed or invalid input, 413 for size
+limits, and 409 for identity conflicts or rejected resumes. `ConfigurationError`
+is a host setup error. An active duplicate raises `StreamError`; the Rails
+adapter refuses it before committing the stream with 409.
+
+A provider or tool failure becomes a sanitized `RUN_ERROR` and failed record.
+A cooperative cancellation becomes a cancelled outcome. A `PersistenceError`
+propagates because acknowledgement may be uncertain. Inspect storage before
+recovery; do not infer whether an external tool effect happened from that error.
+A `RunConflictError`, including `StaleRecordError`, also propagates.
+
+The Rails entry point is `stream_ag_ui_run { |input| authorized_chat }`.
+Override `ag_ui_scope` and optionally `ag_ui_state`. Configure storage with
+`config.run_store`. Private concern helpers are not extension API. Follow the
+[Rails guide]({% link _advanced/rails-integration.md %}) for their signatures.
+
+## Avoid Orchestration Internals
+
+`Emitter`, `Resume`, `Reconnect`, `MessageParser`, input parser helpers,
+`Validation`, `ErrorSanitizer`, `Persistence`, and `Immutable` are internal.
+Their names, constructors, and methods can change without an application API
+migration. Store private helpers and generated Rails model internals have the
+same boundary.
+
+## Next Steps
+
+* [API Reference]({% link _reference/api-reference.md %}) - inspect source signatures.
+* [Compatibility]({% link _reference/compatibility.md %}) - read tested versions and limits.
+* [Upgrading]({% link _reference/upgrading.md %}) - adapt older applications.

data/docs/_reference/release-history.md

@@ -17,7 +17,8 @@ description: Review RubyLLM AG-UI releases, newest first, with highlights and up
 
 | Release | Date | Highlights |
 | --- | --- | --- |
-| [0.3.0](https://github.com/yorzi/ruby_llm-ag-ui/releases/tag/v0.3.0) | 2026-10-20 | [Lifecycle and worker recovery]({% link _getting_started/whats-new-in-0-3.md %}): disconnect handling, scoped cancellation, and conditional durable writes |
+| [0.4.0](https://github.com/yorzi/ruby_llm-ag-ui/releases/tag/v0.4.0) | 2026-10-21 | [API and compatibility]({% link _getting_started/whats-new-in-0-4.md %}): effective configuration, immutable records, and real-chat approval verification |
+| [0.3.0](https://github.com/yorzi/ruby_llm-ag-ui/releases/tag/v0.3.0) | 2026-10-20 | [Lifecycle and worker recovery]({% link _reference/whats-new-in-0-3.md %}): disconnect handling, scoped cancellation, and conditional durable writes |
 | [0.2.0](https://github.com/yorzi/ruby_llm-ag-ui/releases/tag/v0.2.0) | 2026-10-19 | [Client workflows and tool progress]({% link _reference/whats-new-in-0-2.md %}): opt-in redacted progress, a real-client demo, and completed resume reconnect |
 | [0.1.0](https://github.com/yorzi/ruby_llm-ag-ui/releases/tag/v0.1.0) | 2026-10-18 | [First release]({% link _reference/whats-new-in-0-1.md %}): AG-UI event mapping, approval and resume, cancellation, reconnect, and the optional Rails adapter |
 

data/docs/_reference/upgrading.md

@@ -15,42 +15,34 @@ After reading this guide, you will know:
 * How to move between versioned releases.
 * Where to find changes that need code updates.
 
-## Move from 0.2 to 0.3
+## Move from 0.3 to 0.4
 
-Drain your old workers, change your Gemfile, and update the dependency:
+Update your Gemfile and dependency:
 
 ```ruby
-gem 'ruby_llm-ag_ui', '~> 0.3.0'
+gem 'ruby_llm-ag_ui', '~> 0.4.0'
 ```
 
 ```sh
 bundle update ruby_llm-ag_ui
 ```
 
-Version 0.3 requires JSON 2.x. Rails 8.0 passes an option removed in JSON 3
-when RubyLLM loads its chat class. If your Gemfile pins JSON 3, remove that pin
-or select JSON 2.x before updating. This bound also applies to plain Ruby hosts.
-
-`Run` now continues after a response write or flush fails. It saves the real
-outcome instead of reporting the disconnected client as a failed run. Hosts
-that previously relied on disconnects to stop work must explicitly request
-cancellation on the authorized chat. `SSEWriter` still raises a `StreamError`
-subclass when used directly. See
-[Streaming Runs]({% link _core_features/streaming-runs.md %}).
-
-Store writes now use an atomic revision check. Always retain the record returned
-by `save`. Custom stores must implement this contract before upgrading. Existing
-JSON payloads load with revision zero and the shipped table needs no migration.
-Drain old workers first, since 0.2 writers do not enforce revision checks.
-`PersistenceError` now propagates storage failures without guessing a terminal
-outcome. Read [Worker Recovery]({% link _advanced/worker-recovery.md %}) for
-explicit recovery and external-effect reconciliation.
-
-Faraday request timeouts now use `transport_timeout` instead of the generic
-`transport_error` code. Both remain failed outcomes. See
-[Cancellation and Timeouts]({% link _core_features/cancellation.md %}).
+This release keeps JSON 2.x and the 0.3 store revision contract. It needs no
+additional SQL migration. Drain old workers before replacing their code.
+
+Remove assignments to `config.allow_client_history`. The unused setting is
+removed, including its diagnostic key. The gem never imports client messages
+into the host chat; reconcile history in your host application.
+
+`config.protocol_version` remains `"1.0"`. Assigning any other value now raises
+`ConfigurationError` instead of accepting a setting the emitted events ignore.
+
+Nested request and JSON record values are now read-only. In-place edits raise
+`FrozenError`. Build a new input, or use record transitions and `store.save`,
+instead of mutating ids, snapshots, failure hashes, or interrupt values.
+Caller-owned JSON objects remain mutable and do not alias the stored record.
 
 ## Older Releases
 
-For earlier upgrade steps, read the
-[0.2 upgrading guide](https://github.com/yorzi/ruby_llm-ag-ui/blob/v0.2.0/docs/_reference/upgrading.md).
+Read the [0.3 upgrading guide](https://github.com/yorzi/ruby_llm-ag-ui/blob/v0.3.0/docs/_reference/upgrading.md)
+for JSON 2.x, worker draining, and the custom-store revision contract.

data/docs/{_getting_started → _reference}/whats-new-in-0-3.md

@@ -1,7 +1,8 @@
 ---
 layout: default
 title: "What's New in 0.3"
-nav_order: -1
+nav_order: 30
+parent: Release History
 description: Verify transport failure, scoped cancellation, and explicit worker recovery.
 ---
 

data/lib/ruby_llm/ag_ui/configuration.rb

@@ -10,8 +10,8 @@ module RubyLLM
     #     config.logger    = Rails.logger
     #   end
     #
-    # Every value can be overridden per run by passing the matching keyword to
-    # RubyLLM::AgUI::Run.new.
+    # Run.new can override storage, logging, redaction, clock, interrupt expiry,
+    # and tool progress. Input.parse uses the configured request limits.
     class Configuration
       # The object that reserves run identity and stores interrupts. Defaults
       # to nil; set a RubyLLM::AgUI::Store::MemoryStore for single-process use,
@@ -38,7 +38,17 @@ module RubyLLM
 
       # The AG-UI protocol version this producer speaks, emitted on
       # RUN_STARTED so a consumer can detect a downgrade.
-      attr_accessor :protocol_version
+      attr_reader :protocol_version
+
+      # Accepts only the protocol implemented by this producer. A different
+      # version is refused instead of silently reporting a misleading setting.
+      def protocol_version=(value)
+        unless value == Protocol::PROTOCOL_VERSION
+          raise ConfigurationError, "This producer supports protocol #{Protocol::PROTOCOL_VERSION} only."
+        end
+
+        @protocol_version = value
+      end
 
       # Maximum accepted request body size in bytes.
       attr_accessor :max_input_bytes
@@ -58,23 +68,17 @@ module RubyLLM
       # 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'
+        @protocol_version = Protocol::PROTOCOL_VERSION
         @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
         @emit_tool_progress = false
       end
 
@@ -110,7 +114,6 @@ module RubyLLM
           max_tools: max_tools,
           max_context: max_context,
           interrupt_ttl: interrupt_ttl,
-          allow_client_history: allow_client_history,
           emit_tool_progress: emit_tool_progress
         }
       end

data/lib/ruby_llm/ag_ui/emitter.rb

@@ -14,7 +14,7 @@ module RubyLLM
     # The emitter decides nothing about the outcome and executes nothing. What it
     # owns is the one ordering rule a caller should never have to remember: a
     # run's open text, tool calls and step are closed before the terminal event.
-    class Emitter
+    class Emitter # :nodoc:
       # The run record, including the sequence numbers written so far.
       attr_reader :record
 

data/lib/ruby_llm/ag_ui/error_sanitizer.rb

@@ -9,7 +9,7 @@ module RubyLLM
     # module never does that: it classifies the error by class and returns a
     # fixed, public message. The raw exception goes to the host logger, if the
     # host configured one, and nowhere else.
-    module ErrorSanitizer
+    module ErrorSanitizer # :nodoc:
       # Ordered by specificity. The first ancestor of the error whose name is a
       # key wins, so subclass relationships are respected without loading
       # optional error classes eagerly.

data/lib/ruby_llm/ag_ui/immutable.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # Isolated JSON-shaped values for request and storage boundaries.
+    module Immutable # :nodoc:
+      module_function
+
+      def copy(value)
+        case value
+        when Hash
+          value.to_h { |key, item| [copy(key), copy(item)] }.freeze
+        when Array
+          value.map { |item| copy(item) }.freeze
+        when String, Time
+          value.dup.freeze
+        when ::AgUiProtocol::Core::Types::Model
+          copy_model(value)
+        else
+          value
+        end
+      end
+
+      def copy_model(value)
+        value.dup.tap do |model|
+          model.instance_variables.each do |name|
+            model.instance_variable_set(name, copy(model.instance_variable_get(name)))
+          end
+        end.freeze
+      end
+      private_class_method :copy_model
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/input.rb

@@ -17,8 +17,8 @@ module RubyLLM
     #
     # Nothing here grants trust. Client messages, state, tools, context and
     # forwardedProps are accepted as data only; the host decides which tools
-    # and model a run may use, and client history is reconciled by id against
-    # host-stored history rather than appended as trusted system or tool turns.
+    # and model a run may use. This gem never reconciles or appends client
+    # history to the host chat. The host owns that policy.
     class Input
       # The protocol versions this gem can act on.
       SUPPORTED_PROTOCOL_VERSIONS = [Protocol::PROTOCOL_VERSION].freeze
@@ -71,6 +71,7 @@ module RubyLLM
       end
 
       def initialize(attributes)
+        attributes = Immutable.copy(attributes)
         @thread_id = attributes[:thread_id]
         @run_id = attributes[:run_id]
         @parent_run_id = attributes[:parent_run_id]
@@ -118,7 +119,7 @@ module RubyLLM
       #
       # Kept separate from Input so the value object stays immutable and every
       # failure message stays in one place.
-      class Parser
+      class Parser # :nodoc:
         include Validation
 
         MAX_NESTING = 32
@@ -246,7 +247,7 @@ module RubyLLM
 
       # Builds the composite members of a RunAgentInput: the client tool
       # definitions, the context entries and the resume entries.
-      class PartBuilder
+      class PartBuilder # :nodoc:
         include Validation
 
         def tools(values)

data/lib/ruby_llm/ag_ui/interrupt.rb

@@ -69,15 +69,15 @@ module RubyLLM
       # rubocop:disable Metrics/ParameterLists -- one keyword per field the value object owns
       def initialize(id:, tool_call_id:, arguments_digest:, expires_at:, reason: REASON_TOOL_CALL,
                      message: nil, status: PENDING, decided_at: nil, created_at: nil)
-        @id = id
-        @tool_call_id = tool_call_id
-        @arguments_digest = arguments_digest
-        @expires_at = expires_at
-        @reason = reason
-        @message = message
+        @id = Immutable.copy(id)
+        @tool_call_id = Immutable.copy(tool_call_id)
+        @arguments_digest = Immutable.copy(arguments_digest)
+        @expires_at = Immutable.copy(expires_at)
+        @reason = Immutable.copy(reason)
+        @message = Immutable.copy(message)
         @status = assert_status!(status)
-        @decided_at = decided_at
-        @created_at = created_at
+        @decided_at = Immutable.copy(decided_at)
+        @created_at = Immutable.copy(created_at)
         freeze
       end
 
@@ -146,7 +146,7 @@ module RubyLLM
           reason: reason,
           message: message,
           tool_call_id: tool_call_id,
-          expires_at: expires_at&.utc&.iso8601
+          expires_at: expires_at&.getutc&.iso8601
         )
       end
 
@@ -194,7 +194,7 @@ module RubyLLM
       private
 
       def iso8601(time)
-        time&.utc&.iso8601
+        time&.getutc&.iso8601
       end
 
       def assert_status!(value)

data/lib/ruby_llm/ag_ui/mapper.rb

@@ -60,6 +60,12 @@ module RubyLLM
         @closed = false
       end
 
+      # Internal resume bookkeeping: these calls were already reported by the
+      # interrupted run. Only their result and progress belong to this run.
+      def continue_tool_calls(ids) # :nodoc:
+        @continued_tool_call_ids = ids.dup.freeze
+      end
+
       # One streamed Chunk from Chat#complete.
       def chunk(chunk)
         return [] if @closed
@@ -185,6 +191,8 @@ module RubyLLM
         return [] if tool_calls.nil? || tool_calls.empty?
 
         tool_calls.flat_map do |key, tool_call|
+          next [] if @continued_tool_call_ids&.include?(tool_call.id)
+
           record = track(key, tool_call, streamed: streamed)
           open_tool_call(record) + argument_events(record, tool_call, streamed: streamed)
         end

data/lib/ruby_llm/ag_ui/message_parser.rb

@@ -9,7 +9,7 @@ module RubyLLM
     # gem never trusts a client message as a system instruction or a tool
     # result. This parser only guarantees the shapes the pinned schema defines,
     # so a mismatch is a clear InputError instead of a downstream surprise.
-    class MessageParser
+    class MessageParser # :nodoc:
       include Validation
 
       # The roles the pinned schema defines.

data/lib/ruby_llm/ag_ui/reconnect.rb

@@ -12,7 +12,7 @@ module RubyLLM
     # What cannot be served this way is a run that has not ended: attaching a
     # second stream to a live run needs a relay the gem does not own, and a
     # silent second stream would duplicate the work. Those are refused.
-    class Reconnect
+    class Reconnect # :nodoc:
       # The failure reported for a run that failed before its sanitized error
       # was recorded — a record from an older release, or one whose write was
       # interrupted.

data/lib/ruby_llm/ag_ui/resume.rb

@@ -15,7 +15,7 @@ module RubyLLM
     #
     # An approval answers an interrupt. The host still re-authorizes the actor
     # before the tool executes.
-    class Resume
+    class Resume # :nodoc:
       # One entry's effect: the interrupt it answers and the decision to record.
       Decision = Struct.new(:interrupt, :decision, keyword_init: true)
 

data/lib/ruby_llm/ag_ui/resume_entry.rb

@@ -25,9 +25,9 @@ module RubyLLM
       attr_reader :payload
 
       def initialize(interrupt_id:, status:, payload: nil)
-        @interrupt_id = interrupt_id
-        @status = status
-        @payload = payload
+        @interrupt_id = Immutable.copy(interrupt_id)
+        @status = Immutable.copy(status)
+        @payload = Immutable.copy(payload)
         freeze
       end
 

data/lib/ruby_llm/ag_ui/run.rb

@@ -20,7 +20,8 @@ module RubyLLM
     # input, because a scope derived from anything the client sent would let one
     # client attach to another's run.
     class Run
-      # The run's authoritative record, once it has been reserved.
+      # The reserved record or final outcome observed by this run, including a
+      # reconnect. Nil before the run obtains its reservation.
       attr_reader :record
 
       # rubocop:disable-next Metrics/ParameterLists -- one keyword per host-supplied or overridable value
@@ -52,16 +53,15 @@ module RubyLLM
       def stream(to:)
         resume.plan(now: @clock.call) if resume.needed?
         reservation = reserve
-        return execute(reservation.record, to) if reservation.created?
+        @record = reservation.record
+        return execute(@record, to) if reservation.created?
 
-        reconnect(reservation.record, to)
+        reconnect(@record, to)
       end
 
       private
 
-      def resume
-        @resume ||= Resume.new(input: @input, store: @store, scope: @scope, chat: @chat)
-      end
+      def resume = @resume ||= Resume.new(input: @input, store: @store, scope: @scope, chat: @chat)
 
       def reserve
         Persistence.write do
@@ -102,6 +102,7 @@ module RubyLLM
 
       def start_execution(record, to)
         @mapper = build_mapper(record)
+        @mapper.continue_tool_calls(@chat.pending_approvals.map(&:id)) if resume.needed?
         @emitter = build_emitter(record, to, mapper: @mapper)
         @emitter.start(run_started_event(record), state: @state)
       end

data/lib/ruby_llm/ag_ui/run_record.rb

@@ -72,18 +72,18 @@ module RubyLLM
       # rubocop:disable-next Metrics/ParameterLists -- one keyword per field the record owns
       def initialize(scope:, thread_id:, run_id:, digest:, created_at:, status: RESERVED, sequence: 0,
                      snapshot: nil, interrupts: [], failure: nil, updated_at: nil, revision: 0)
-        @scope = scope
-        @thread_id = thread_id
-        @run_id = run_id
-        @digest = digest
+        @scope = Immutable.copy(scope)
+        @thread_id = Immutable.copy(thread_id)
+        @run_id = Immutable.copy(run_id)
+        @digest = Immutable.copy(digest)
         @status = assert_status!(status)
         @sequence = sequence
         @revision = revision
-        @snapshot = snapshot
-        @interrupts = interrupts.freeze
-        @failure = failure
-        @created_at = created_at
-        @updated_at = updated_at || created_at
+        @snapshot = Immutable.copy(snapshot)
+        @interrupts = Immutable.copy(interrupts)
+        @failure = Immutable.copy(failure)
+        @created_at = Immutable.copy(created_at)
+        @updated_at = Immutable.copy(updated_at || created_at)
         freeze
       end
 
@@ -229,7 +229,7 @@ module RubyLLM
       end
 
       def iso8601(time)
-        time&.utc&.iso8601
+        time&.getutc&.iso8601
       end
 
       def assert_status!(value)

data/lib/ruby_llm/ag_ui/store/memory_store.rb

@@ -34,7 +34,7 @@ module RubyLLM
             )
             @records[key] = record
             thread = thread_key(scope, thread_id)
-            @threads[thread] = (@threads[thread] || []) + [run_id]
+            @threads[thread] = (@threads[thread] || []) + [record.run_id]
             Reservation.new(record: record, status: Reservation::CREATED)
           end
         end
@@ -107,11 +107,11 @@ module RubyLLM
         end
 
         def key_for(scope, thread_id, run_id)
-          [scope_key(scope), thread_id, run_id]
+          Immutable.copy([scope_key(scope), thread_id, run_id])
         end
 
         def thread_key(scope, thread_id)
-          [scope_key(scope), thread_id]
+          Immutable.copy([scope_key(scope), thread_id])
         end
       end
     end

data/lib/ruby_llm/ag_ui/validation.rb

@@ -9,7 +9,7 @@ module RubyLLM
     # the client without echoing request bytes back.
     #
     # Included by RubyLLM::AgUI::Input::Parser and RubyLLM::AgUI::MessageParser.
-    module Validation
+    module Validation # :nodoc:
       # The longest accepted id (threadId, runId, message id, interrupt id).
       MAX_ID_LENGTH = 255
 

data/lib/ruby_llm/ag_ui/version.rb

@@ -3,6 +3,6 @@
 module RubyLLM
   module AgUI
     # The version of the ruby_llm-ag_ui gem, as a string.
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-ag_ui
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Andy Wang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ag-ui-protocol
@@ -163,6 +163,7 @@ files:
 - README.md
 - SECURITY.md
 - docs/_advanced/client-example.md
+- docs/_advanced/provider-verification.md
 - docs/_advanced/rails-integration.md
 - docs/_advanced/security-and-deployment.md
 - docs/_advanced/worker-recovery.md
@@ -175,16 +176,18 @@ files:
 - docs/_getting_started/configuration.md
 - docs/_getting_started/getting-started.md
 - docs/_getting_started/overview.md
-- docs/_getting_started/whats-new-in-0-3.md
+- docs/_getting_started/whats-new-in-0-4.md
 - docs/_reference/api-reference.md
 - docs/_reference/compatibility.md
 - docs/_reference/protocol-coverage.md
+- docs/_reference/public-api.md
 - docs/_reference/release-history.md
 - docs/_reference/releasing.md
 - docs/_reference/third-party-notices.md
 - docs/_reference/upgrading.md
 - docs/_reference/whats-new-in-0-1.md
 - docs/_reference/whats-new-in-0-2.md
+- docs/_reference/whats-new-in-0-3.md
 - docs/index.md
 - lib/generators/ruby_llm/ag_ui/install_generator.rb
 - lib/generators/ruby_llm/ag_ui/templates/create_ruby_llm_ag_ui_runs.rb.tt
@@ -196,6 +199,7 @@ files:
 - lib/ruby_llm/ag_ui/emitter.rb
 - lib/ruby_llm/ag_ui/error.rb
 - lib/ruby_llm/ag_ui/error_sanitizer.rb
+- lib/ruby_llm/ag_ui/immutable.rb
 - lib/ruby_llm/ag_ui/input.rb
 - lib/ruby_llm/ag_ui/interrupt.rb
 - lib/ruby_llm/ag_ui/mapper.rb