ruby_llm-ag_ui 0.1.0

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

@@ -0,0 +1,204 @@
+---
+layout: default
+title: "Security and Deployment"
+nav_order: 2
+description: Keep identity, tool permissions, and sensitive output under the host application's control.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* Which values the gem treats as untrusted.
+* How redaction, error sanitization, and interrupt redemption work.
+* Which security decisions the host application must make.
+
+This gem is a **producer**, not an authorization layer. It decides what a run may
+report on the wire and refuses what it cannot report truthfully. It does not
+decide who may run what: authentication, authorization, which tools and model an
+actor may use, and whether a tool may execute are the host's decisions.
+
+The model below is the one the test suite enforces, and the negative cases are
+fixtures, not prose. If a claim here has no test, it is marked as host
+responsibility.
+
+## Trust boundaries
+
+| Input | Trusted? | Why |
+|---|---|---|
+| `messages`, `state`, `tools`, `context`, `forwardedProps` | **No** | Arbitrary JSON from the client. Accepted as data only. |
+| `threadId`, `runId`, `parentRunId`, `resume` | **No** | They name things; they never select a record or grant a right. |
+| `protocolVersion` | **No** | Reported and compared; an unknown version is refused, not honored. |
+| The `scope` string | **Yes, because the host built it** | It must come from authenticated identity. The gem rejects a non-String or empty scope. |
+| The `chat` object | **Yes** | The host constructed it, with the host's tools and model. |
+| Tool output | **No** | A tool reads databases, APIs and files. Its payload can hold secrets and personal data. |
+| Provider exceptions | **No** | They can embed request bodies, URLs, headers and keys. |
+| The run store | **Yes** | Host infrastructure. |
+
+## What a client cannot do
+
+- **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.
+- **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
+  another tenant run").
+- **Redeclare a run id.** The same identity with a *different* input is refused
+  as `RunConflictError` (409 in the Rails adapter) rather than executed
+  ("refuses the same identity with a changed input as a conflict").
+- **Run the same tool twice.** A resume is recorded once; a second answer to the
+  same interrupt is refused without executing the tool ("refuses a decision
+  another resume already recorded, without executing the tool").
+- **Widen what an approval covers.** An interrupt pins the tool call and the
+  digest of the arguments RubyLLM asked to run. A resume whose call arguments
+  changed, whose call is no longer pending, or which names an interrupt that
+  expired or does not exist is refused before anything is reserved or written
+  ("refuses a resume whose tool call arguments changed since the interrupt",
+  "refuses an expired interrupt", "refuses an unknown interrupt before the run is
+  reserved or opened").
+- **Inject SSE framing.** Every frame is one JSON document on one `data:` line;
+  a payload containing newlines stays inside the JSON string. There is no path
+  that writes a raw payload into a frame.
+- **Exhaust the process with one body.** The body is bounded before it is parsed
+  (`max_input_bytes`, 256 KB default), and so are message, tool and context
+  counts.
+
+## Redaction is the default
+
+`config.redact` defaults to `RubyLLM::AgUI::Redaction.method(:default)`: the
+payload keeps its **shape** and loses its **content** (`[redacted]`), because the
+gem cannot know which part of a tool result is a secret. The mapper warns once per
+run that the host has not chosen a policy
+(`spec/ruby_llm/ag_ui/mapper_spec.rb`: "keeps the shape and withholds the
+content", "warns once that the host has not chosen a policy").
+
+Opting out is explicit:
+
+```ruby
+RubyLLM::AgUI.configure do |config|
+  config.redact = RubyLLM::AgUI::Redaction.method(:none)   # publish as-is
+  # or
+  config.redact = ->(kind, payload) { MyPolicy.call(kind, payload) }
+end
+```
+
+A `nil` policy is not an opt-out: `Configuration#redact` falls back to the
+default, so a mistyped configuration cannot publish raw payloads. What is in
+force is reported by `RubyLLM::AgUI.config.to_h[:redact]` as `:default`, `:none`
+or `:custom`.
+
+Redaction applies to what the gem publishes. It does not scrub the host's logs,
+the chat's own history, the provider's copy of the conversation, or any payload
+the host writes to the wire by other means.
+
+## Errors never carry exception text
+
+`RUN_ERROR` is built from `ErrorSanitizer`: a fixed message and code per error
+class, and a fixed `internal_error` fallback for anything unrecognized. The raw
+exception goes to the host logger, if one is configured, and nowhere else
+(`spec/ruby_llm/ag_ui/run_spec.rb`: "never echoes the exception text";
+`spec/ruby_llm/ag_ui/error_sanitizer_spec.rb`).
+
+This matters because upstream Rails examples put `e.message` straight into the
+event. A provider error message can contain the prompt, the tool arguments, a URL
+with a key in it, or an internal path.
+
+## Interrupts
+
+An interrupt is a pause, not a permission. It carries the tool call id, a reason,
+a human-readable question, and a host-owned expiry. It does **not** carry the
+arguments digest that the resume check uses ("does not let the arguments digest
+reach the client"), so the client cannot forge a matching approval.
+
+- TTL is `config.interrupt_ttl` (900 s default) or per-run `expires_in:`.
+- An expired interrupt is not answerable; a resume for it is refused.
+- A resume with `status: "cancelled"` records a denial. The chat's next
+  `complete` reports the denial as RubyLLM normally would; no tool runs.
+- Approval does not skip the host's re-authorization: the host re-checks before
+  a tool executes, and the gem cannot do it for them.
+
+The store's redemption step is the concurrency guard: the first decision wins and
+is recorded, the loser is told it was already recorded. That is why an approved
+tool executes once even when two resumes arrive together.
+
+## Reconnect
+
+A run that already ended is served from its record: `RUN_STARTED` (with the
+protocol version and the input echo), `STATE_SNAPSHOT` when one was recorded, and
+the recorded terminal event. Deltas are never replayed, and a run that has not
+ended is refused rather than attached ("refuses to attach a second stream to a run
+that has not ended"). Both rules exist to prevent a duplicated side effect, not
+just duplicated text.
+
+A recorded failure is reported with the sanitized message and code it was stored
+with. A record with no recorded failure reports `internal_error` rather than
+guessing.
+
+## Transport
+
+The gem writes to whatever object the host gives it and sets no security policy
+of its own beyond the framing. The Rails adapter adds:
+
+- `Accept` negotiation: a client that cannot read `text/event-stream` gets 406
+  before any event.
+- Input refusal before the response commits: 400, 404, 409, 413, never a
+  half-open stream.
+- `Content-Type: text/event-stream`, `Cache-Control: no-cache`,
+  `Connection: keep-alive`, `X-Accel-Buffering: no`.
+- A client disconnect is swallowed: it is not a run outcome.
+
+The gem does not terminate TLS, authenticate, rate-limit, validate Origin/CSRF
+for browser clients, or configure CORS. Those are the host's, and getting them
+wrong is outside what this gem can detect.
+
+## Deployment checklist
+
+1. Authenticate before parsing the body; build `scope` from the authenticated
+   actor, never from anything in the body.
+2. Authorize the `threadId → chat` lookup inside the actor's own association, so
+   a client-chosen id cannot select somebody else's conversation.
+3. Re-authorize before an approved tool runs. An approval answers an interrupt;
+   it does not grant permission.
+4. Use a durable store with a uniqueness constraint on
+   `(scope, thread_id, run_id)` and `(scope, thread_id, interrupt_id)`. The Rails
+   store is built for that; `MemoryStore` is single-process only.
+5. Keep redaction on until you have classified which payloads may be published.
+   Scrub raw bodies, prompts and tool payloads out of your logs.
+6. Treat `messages`, `state` and `forwardedProps` as untrusted text in any UI you
+   build. Escape it where it is rendered; a producer cannot prevent XSS.
+7. Bound the resource: request size (`max_input_bytes`), provider timeouts, rate
+   limits, and the number of concurrent streams (an `ActionController::Live`
+   response holds a thread for the run's lifetime).
+8. Serve over TLS, and set CORS and cookie policy deliberately if the stream is
+   consumed from a browser.
+9. Do not enable client-supplied tools for a multi-tenant deployment in this
+   release; they are never used, and that is the intended behavior.
+10. Do not log the request body or the events at info level.
+
+## What is out of scope
+
+- **Prompt injection.** Content that arrives in `messages`, tool results or
+  documents can steer a model. This gem maps the model's behavior faithfully; it
+  cannot make the model trustworthy.
+- **Host authentication and authorization**, including whether a given actor
+  should be allowed to run a given tool.
+- **Provider-side data handling**, retention and training.
+- **Anything the host writes outside the gem's events**, such as its own log lines,
+  its own extra SSE frames, its own UI.
+- **Denial of service by an authenticated actor** who opens many legitimate
+  streams.
+
+## Reporting
+
+See the [repository security policy](https://github.com/yorzi/ruby_llm-ag-ui/blob/main/SECURITY.md) for the reporting process. Reports about a silent duplicate execution, an approval that widens what it covers, a secret in a `RUN_ERROR`, or a leak into the log are treated as vulnerabilities.
+
+## Next Steps
+
+* [Configuration]({% link _getting_started/configuration.md %}) - set safe redaction and storage defaults.
+* [Rails Integration]({% link _advanced/rails-integration.md %}) - apply these boundaries in a controller.

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

@@ -0,0 +1,62 @@
+---
+layout: default
+title: "Approval and Resume"
+nav_order: 3
+description: "Pause a run for host-authorized tool approval and answer the interrupt on a new run."
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* What an approval interrupt contains.
+* How the client answers it on a new run.
+* What the host must authorize again before a tool executes.
+
+## Return an Interrupt
+
+When RubyLLM pauses on `requires_approval`, the run ends with an interrupt outcome. The interrupt identifies the pending tool call and includes a host-owned expiry. The id and expiry below are from a sample run; each run receives new values.
+
+```json
+{
+  "type": "RUN_FINISHED",
+  "threadId": "thread-1",
+  "runId": "run-1",
+  "outcome": {
+    "type": "interrupt",
+    "interrupts": [{
+      "id": "817cc7a4-c2b4-4393-a25b-09819cf7198a",
+      "reason": "tool_call_confirmation",
+      "message": "Approve the cancel_order tool call?",
+      "toolCallId": "call_cancel_42",
+      "expiresAt": "2026-10-18T02:19:38Z"
+    }]
+  }
+}
+```
+
+The interrupt does not expose the tool arguments digest used by the server. A client cannot use the response as a permission token.
+
+## Answer on a New Run
+
+The client sends a new `runId` for the same thread and includes a resume entry. `resolved` approves the pending call; `cancelled` records a denial.
+
+```json
+{
+  "threadId": "thread-1",
+  "runId": "run-2",
+  "messages": [{ "id": "m1", "role": "user", "content": "Cancel order 42." }],
+  "resume": [{ "interruptId": "817cc7a4-c2b4-4393-a25b-09819cf7198a", "status": "resolved" }]
+}
+```
+
+The interrupt must still be pending and unexpired. The tool call id and argument digest must match the call RubyLLM is holding. The host must re-authorize the action before the tool executes. The store records only one decision, so a replay cannot execute the tool twice.
+
+## Next Steps
+
+* [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.

data/docs/_core_features/input-validation.md

@@ -0,0 +1,64 @@
+---
+layout: default
+title: "Validating Input"
+nav_order: 1
+description: "Validate a bounded AG-UI request and turn it into immutable values."
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to parse a request body and inspect its typed values.
+* How unknown members, size limits, and validation errors work.
+* Which request values remain untrusted after parsing.
+
+## Parse a Request
+
+`RunAgentInput` arrives as JSON. Parse it before choosing a chat so malformed or oversized input is refused before provider work begins.
+
+```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].join('/')
+# => thread-1/run-1
+```
+
+`Input.parse` accepts a JSON string, a Hash, or a readable stream. The result is immutable. It exposes the accepted values, a canonical digest, and any non-fatal warnings.
+
+## Unknown Members and Limits
+
+By default, top-level members outside the pinned schema are stripped and recorded in `warnings`. Set `strict: true` to reject them. The parser also bounds the request body, nesting depth, and counts for messages, tools, and context.
+
+```ruby
+input = RubyLLM::AgUI::Input.parse({
+  'threadId' => 'thread-1',
+  'runId' => 'run-1',
+  'messages' => [],
+  'clientOnly' => true
+})
+
+input.warnings
+# => ["stripped unknown RunAgentInput member \"clientOnly\""]
+```
+
+Pass `max_bytes:` to set a per-parse body limit. Configure `max_messages`, `max_tools`, and `max_context` on `RubyLLM::AgUI.config`. Invalid JSON, unsupported protocol versions, missing identifiers, and invalid message shapes raise an `InputError` subclass before a run starts.
+
+## Parsed Data Does Not Grant Trust
+
+The parser validates shape, not authority. Client-supplied tools are reported by `tool_names` and `client_tools?`, but they are never registered on the chat. The host chooses the model, tools, system prompt, chat history, and authenticated scope. Do not use `thread_id` or `run_id` as authorization by themselves.
+
+## Next Steps
+
+* [Getting Started]({% link _getting_started/getting-started.md %}) - install and parse a request.
+* [Streaming Runs]({% link _core_features/streaming-runs.md %}) - pass a validated input to a RubyLLM chat.
+* [Security and Deployment]({% link _advanced/security-and-deployment.md %}) - define the host trust boundary.

data/docs/_core_features/reconnects.md

@@ -0,0 +1,42 @@
+---
+layout: default
+title: "Reconnects and Run Identity"
+nav_order: 4
+description: "Reserve each run once and report its recorded outcome after a reconnect."
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How the gem reserves `(scope, threadId, runId)` for one input digest.
+* How retries and reconnects differ from duplicate execution.
+* Which store to use for one process or several workers.
+
+## Reuse a Run Identity
+
+The store reserves a run before any provider work. It keys the record by authenticated scope, thread id, and run id, then compares the canonical digest of the accepted input.
+
+| Request | Result |
+| --- | --- |
+| New identity | Reserve and execute the run. |
+| Same identity and same input while running | Refuse a second live stream. |
+| Same identity and same input after completion | Return the recorded start, optional state snapshot, and terminal event. |
+| Same identity with different input | Raise a run conflict. |
+
+Reconnect does not replay text or tool deltas. Replaying deltas could display text twice or repeat a side effect. The host can publish a state snapshot for a finished run, but the gem does not reconstruct conversation history.
+
+## Choose a Store
+
+`MemoryStore` is suitable for tests and a single process. Its records disappear on restart and are not shared between workers. The Rails adapter's `ActiveRecordStore` persists records and redeems interrupts under a database lock.
+
+The store boundary is `RubyLLM::AgUI::Store::Base`. Configure a compatible store globally or pass it to `Run.new`. For multi-process deployments, the database must enforce unique run identity and serialize interrupt redemption.
+
+## Next Steps
+
+* [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.

data/docs/_core_features/streaming-runs.md

@@ -0,0 +1,49 @@
+---
+layout: default
+title: "Streaming Runs"
+nav_order: 2
+description: "Run one RubyLLM chat turn and write ordered AG-UI events as server-sent events."
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to connect a host-owned chat, parsed input, scope, and store.
+* How a RubyLLM turn becomes ordered AG-UI events.
+* What each terminal outcome means.
+
+## Run a Complete Example
+
+The repository includes a scripted chat that emits an approval pause, resumes the tool call, and prints the server-sent events. Run it from the repository root; it does not need a provider key.
+
+```sh
+bundle exec rake example
+```
+
+In an application, parse the request first, then pass the host-selected chat, parsed input, authenticated scope, and run store to `RubyLLM::AgUI::Run`. Call `stream(to:)` with an IO-like stream. The host builds the chat and authorizes access to the thread; the gem reserves the run identity before provider work.
+
+## Event Order
+
+The mapper turns RubyLLM callbacks into AG-UI events. The emitter assigns each event a sequence, persists run state, closes open text or tool events, and writes one JSON event per `data:` line through the SSE writer.
+
+An assistant message opens on its first non-empty chunk and closes before a tool call, phase change, or terminal event. A tool call starts when its id and name are known, emits the arguments as received, and ends before the call runs. One run ends with one terminal result.
+
+## Outcomes
+
+* A completed chat ends with `RUN_FINISHED` and a `success` outcome.
+* A `requires_approval` pause ends with `RUN_FINISHED` and an `interrupt` outcome.
+* `Chat#cancel` ends with `RUN_FINISHED` and a `cancelled` outcome.
+* A failure ends with `RUN_ERROR` and a sanitized message and code.
+* A pause the protocol cannot express is an error, never a success.
+
+The run record reaches a terminal state before the terminal event is written. If the connection closes in the middle, the record remains available for a later reconnect.
+
+## Next Steps
+
+* [Validating Input]({% link _core_features/input-validation.md %}) - parse untrusted request data.
+* [Approval and Resume]({% link _core_features/approval-and-resume.md %}) - answer an interrupt on a new run.
+* [Reconnects and Run Identity]({% link _core_features/reconnects.md %}) - serve a completed run again.

data/docs/_getting_started/configuration.md

@@ -0,0 +1,57 @@
+---
+layout: default
+title: Configuration
+nav_order: 3
+description: Set run storage, input limits, logging, and redaction defaults for the application.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to configure defaults once for the application.
+* Which settings are available and what each one controls.
+
+## Configuring RubyLLM AG-UI
+
+```ruby
+require 'ruby_llm/ag_ui'
+
+RubyLLM::AgUI.configure do |config|
+  config.run_store = RubyLLM::AgUI::Store::MemoryStore.new
+  config.max_input_bytes = 256_000
+  config.redact = RubyLLM::AgUI::Redaction.method(:default)
+end
+
+p RubyLLM::AgUI.config.to_h[:redact]
+# => :default
+```
+
+## Settings
+
+The global configuration supplies defaults. `Run.new` can override the store, logger, redaction policy, clock, and interrupt expiry for one run. `MemoryStore` is process-local, so use a durable store when runs can move between workers.
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `run_store` | `nil` | Store run records and interrupts. A run needs a store, supplied here or to `Run.new`. |
+| `redact` | `Redaction.default` | Transform tool results before they reach the stream. |
+| `logger` | `nil` | Receive host-side diagnostics without prompts or raw tool payloads. |
+| `protocol_version` | `"1.0"` | Value reported by `RUN_STARTED`. |
+| `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. |
+
+Provider keys and model selection are configured through RubyLLM and the host app. This gem does not read credentials when it loads.
+
+## Next Steps
+
+* [Getting Started]({% link _getting_started/getting-started.md %}) - install and parse a request.
+* [How RubyLLM AG-UI Works]({% link _getting_started/overview.md %}) - the parts of one run.
+* [Security and Deployment]({% link _advanced/security-and-deployment.md %}) - host responsibilities and safe defaults.

data/docs/_getting_started/getting-started.md

@@ -0,0 +1,52 @@
+---
+layout: default
+title: Getting Started
+nav_order: 1
+description: Install ruby_llm-ag_ui and validate an AG-UI request before connecting a chat.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* How to install the release or the current development branch.
+* How to parse a `RunAgentInput` into validated Ruby values.
+* How to run the included offline end-to-end example.
+
+## Installation
+
+```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 %}
+```
+
+The gem requires Ruby 3.2 or newer, RubyLLM 2.1 or newer, and `ag-ui-protocol` 0.2.x. The Rails adapter is optional. Provider credentials belong to your RubyLLM application; the parser example below needs none.
+
+The runtime dependencies select patched `cgi`, `resolv`, `uri`, and `zlib` gems. An older Ruby installation's default library versions do not override those dependency requirements.
+
+## Parse a Request
+
+Before you start a chat, validate the request body. The parser bounds the input, checks required fields, and returns an immutable value.
+
+```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
+```
+
+The host still chooses the chat, model, tools, and authenticated scope. `Input` treats client fields as data and does not grant access. To see a complete run with an approval pause and resume, run `bundle exec rake example` from the repository; it uses a scripted chat and needs no provider key.
+
+## Next Steps
+
+* [How RubyLLM AG-UI Works]({% link _getting_started/overview.md %}) - the parts of one run.
+* [Configuration]({% link _getting_started/configuration.md %}) - defaults and run stores.
+* [Validating Input]({% link _core_features/input-validation.md %}) - request limits and strict parsing.