llm.rb 15.2.2 → 15.4.0

data/docs/deepdive/features/database.md

@@ -4,10 +4,11 @@
 
 #### Overview
 
-Persistence lets an agent outlive a single session. The conversation
-history, model name, and compaction status are serialized as JSON
-that can be stored in a file, a database column, or transmitted
-over a network. Four storage options are available:
+Persistence lets an agent outlive a single session. The
+conversation history, the context id, the model name, the compaction
+status, and a snapshot of token usage are serialized as JSON that can
+be stored in a file, a database column, or transmitted over a network.
+Four storage options are available:
 
 - **Automatic filesystem persistence**: set `path:` on an agent
   for transparent auto-save after every turn (recommended for
@@ -15,9 +16,13 @@ over a network. Four storage options are available:
 - **Filesystem**: save and restore from a JSON file on disk
 - **ActiveRecord**: persist state in a database column using
   [`acts_as_agent`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord.html#acts_as_agent-instance_method)
+  for an agent, or
+  [`acts_as_llm`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord.html#acts_as_llm-instance_method)
+  for a context
 - **Sequel**: persist state in a database column using `plugin :agent`
+  for an agent, or `plugin :llm` for a context
 
-All three use the same serialization mechanism under the hood.
+All four use the same serialization mechanism under the hood.
 
 #### How it works
 
@@ -161,8 +166,9 @@ and
 for serialization
 and
 [`LLM::Context#restore`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#restore)
-for deserialization. The serialized state includes
-the message history, model name, and compaction status. Save and
+for deserialization. The serialized state includes the context id,
+the message history, the model name, the compaction status, and a
+snapshot of token usage. Save and
 restore work with file paths or in-memory strings. You can also
 serialize to a JSON string for database storage or network
 transmission:
@@ -230,9 +236,10 @@ When you want to add agent persistence to an ActiveRecord model,
 call
 [`LLM::ActiveRecord#acts_as_agent`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord.html#acts_as_agent-instance_method)
 in the model class. The `data` column stores
-the full agent state (conversation history, model name, compaction
-status) as JSON. On first call, a fresh agent is created and the
-conversation starts from scratch.
+the full agent state (the context id, conversation history, model
+name, compaction status, and a token usage snapshot) as JSON. On
+first call, a fresh agent is created and the conversation starts
+from scratch.
 
 On subsequent calls, the stored state is restored and the
 conversation continues. Every
@@ -339,6 +346,67 @@ also work for backwards compatibility, but the block style
 (`agent.tracer ...`, `agent.stream ...`) is preferred for all
 agent-level configuration.
 
+An agent built by `acts_as_agent` is bound to the record it was
+loaded from, and
+[`LLM::Agent#record`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#record)
+returns it. To persist a context instead of an agent, use
+`acts_as_llm`: the model gains `#llm` (the provider) and `#ctx` (the
+context), and persists the same state without the automatic tool
+loop.
+
+### SQL view
+
+#### Overview
+
+[`LLM::ActiveRecord::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html)
+is a virtual ActiveRecord model that never materializes as a table. It
+exposes the messages stored inside an agent's `jsonb` column as a SQL
+view, so a conversation can be filtered, ordered, and counted in the
+database instead of in memory.
+
+#### How it works
+
+Call
+[`LLM::ActiveRecord::Message.for`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html#for-class_method)
+with an agent, and it returns an
+[`ActiveRecord::Relation`](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html)
+scoped to that agent, with one row per message. The relation chains
+like any other:
+
+```ruby
+agent = Agent.find_by(id: 1)
+
+messages = LLM::ActiveRecord::Message.for(agent:)
+messages.where(role: "assistant").order(position: :desc).limit(10)
+messages.count
+```
+
+Each row carries a message flattened into columns: `id`, `role`,
+`content`, `tools`, and `position` (its place in the conversation),
+with the whole message kept as `data`.
+[`LLM::ActiveRecord::Message#unwrap!`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html#unwrap!-instance_method)
+rebuilds the message as the runtime would hand it back, so fields the
+view does not name, such as usage and reasoning, survive the round
+trip. `#tool_call?` and `#tool_return?` delegate to it.
+
+#### Why would I use it?
+
+Reading a conversation through the view keeps the work in the
+database. "How many assistant messages has this agent produced" and
+"show the last ten messages" become ordinary ActiveRecord queries
+instead of loading and filtering the whole conversation in Ruby.
+
+#### Notes
+
+The view expects the agent and this class to share a connection, which
+holds when both live on the same database. It requires
+`format: :jsonb`, since a `:string` column stores the state as text and
+cannot be expanded into rows. The queries the view runs are index
+scans, because they expand one agent found by primary key, but a query
+you write across every agent is not covered by default; index the state
+column for those, for example with a GIN index on
+`data jsonb_path_ops`.
+
 ### Sequel
 
 #### Overview
@@ -447,3 +515,10 @@ also work for backwards compatibility, but configuring tracer,
 stream, and other agent options in the block is the preferred
 approach.
 
+To persist a context instead of an agent, use `plugin :llm`. The
+model gains `#llm` (the provider) and `#ctx` (the context), and
+persists the same state without the automatic tool loop. An agent
+built by `plugin :agent` is bound to its record, which
+[`LLM::Agent#record`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#record)
+returns.
+

data/docs/deepdive/fundamentals/agents.md

@@ -18,20 +18,19 @@ serialization, compaction, and concurrency.
 An agent holds a conversation with a model. You send input with
 [`LLM::Agent#talk`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#talk),
 the model responds, and if it requests tools the agent
-executes them automatically and feeds the results back. It enables
-[a loop guard by default](https://r.uby.dev/llm/deepdive/advanced/guard)
-that detects repeated tool-call patterns
-and blocks stuck execution. The tool loop can also be bounded with
+executes them automatically and feeds the results back. The tool
+loop can be bounded with
 [`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
 (see the Tool budget section). Instructions are injected once
 unless a system message is already present.
 
 #### Why would I use it?
 
-Agents manage the tool loop for you. They guard against infinite
-loops, keep conversation state across turns, and let you define
-reusable configurations at the class level. If you need manual
-control over the tool loop, use
+Agents manage the tool loop for you. They keep conversation state
+across turns and let you define reusable configurations at the
+class level. The loop runs until the model stops requesting tools
+unless you bound it with `tool_budget` or a guard. If you need
+manual control over the tool loop, use
 [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
 directly instead.
 

data/docs/deepdive/fundamentals/providers.md

@@ -5,11 +5,13 @@
 #### Overview
 
 llm.rb talks to 14+ providers through one API. OpenAI-compatible
-providers (Anthropic, DeepSeek, DeepInfra, xAI, Z.ai, Moonshot,
-Alibaba, Ollama, and llama.cpp) share the same OpenAI code path, so
-switching models rarely means switching code. Each provider is
-constructed with a class-level factory method on `LLM`, and the
-result is passed to an `LLM::Context` or `LLM::Agent`.
+providers (DeepSeek, DeepInfra, xAI, Z.ai, Moonshot, Alibaba,
+Mistral, OpenRouter, and llama.cpp) share the same OpenAI code path,
+while Anthropic, Google, Ollama, and Bedrock speak their own APIs
+behind the same interface. Switching models therefore rarely means
+switching code. Each provider is constructed with a class-level
+factory method on `LLM`, and the result is passed to an
+`LLM::Context` or `LLM::Agent`.
 
 #### How it works
 
@@ -90,6 +92,44 @@ missing model or registry raises `LLM::NoSuchModelError` or
 `LLM::NoSuchRegistryError`, which the runtime rescues to default
 gracefully (for example, an unknown context window reads as `nil`).
 
+### Request headers
+
+#### Overview
+
+Every request a provider sends can carry extra HTTP headers, either
+for the lifetime of the provider or for a single call. Some headers
+vary per request, so a provider needs a way to set one without
+affecting the requests that come after it.
+
+#### How it works
+
+[`LLM::Provider#with`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#with-instance_method)
+adds headers. Without a block the headers merge into the provider's
+defaults and apply to every later request:
+
+```ruby
+llm = LLM.openai(key: ENV["KEY"])
+llm.with("OpenAI-Organization" => ENV["ORG"])
+```
+
+With a block the headers apply only to the current fiber and are
+restored when the block returns, so a header can be scoped to one
+call:
+
+```ruby
+llm.with("x-session-id" => "abc123") do
+  ctx.talk "Hello"
+end
+```
+
+#### Notes
+
+The runtime uses the block form where a header varies per request.
+An OpenRouter context sends its own id as `x-session-id`, so
+consecutive requests share a session and OpenRouter can route them to
+the same cached model, without pinning that header on the provider
+for good.
+
 ### Moonshot
 
 #### Overview

data/docs/deepdive/fundamentals/schema.md

@@ -59,3 +59,76 @@ They are also used internally by
 [`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
 for parameter definitions, so you already benefit from them
 when you declare tool parameters.
+
+### Types
+
+#### Overview
+
+A schema is built from a small set of types: the JSON primitives, an
+array of a type, an enum of allowed values, a nested schema, and the
+combinators `any_of`, `all_of`, and `one_of`. Every type takes a
+description, and any type can be marked required or given a default.
+
+#### How it works
+
+A property is declared with its type and description. `String`,
+`Integer`, `Number`, and `Boolean` are the primitives, `Array[Type]`
+wraps one, and `Enum[...]` constrains a value to a fixed set. A nested
+schema is just another `LLM::Schema` subclass used as the type:
+
+```ruby
+class Address < LLM::Schema
+  property :street, String, "Street address"
+  required %i[street]
+end
+
+class Person < LLM::Schema
+  property :name, String, "Person's name"
+  property :age, Integer, "Person's age"
+  property :hobbies, Array[String], "Person's hobbies"
+  property :address, Address, "Person's address"
+  required %i[name age hobbies address]
+end
+```
+
+`Array[String, Integer]` declares an array whose items may be either
+type. Options on `property` set a leaf directly, so
+`property :age, Integer, "Person's age", required: true` marks one
+property required, and
+[`LLM::Schema.defaults`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html#defaults-class_method)
+sets defaults for several at once:
+
+```ruby
+class Search < LLM::Schema
+  property :query, String, "The search query"
+  property :limit, Integer, "The number of results"
+  required %i[query]
+  defaults limit: 10
+end
+```
+
+The same schema can be built without a class, using the value methods:
+
+```ruby
+schema = LLM::Schema.new
+schema.object(
+  name: schema.string.required,
+  age: schema.integer.required,
+  colors: schema.array(schema.string.enum("red", "green")).required
+)
+```
+
+#### Why would I use it?
+
+Types tell the model what shape to produce. A plain `String` is the
+loosest, an `Enum` the tightest, and a nested schema lets a structured
+response contain a structured value. Because the same machinery backs
+tool parameters, anything you learn here applies to tools too.
+
+#### Notes
+
+`any_of`, `all_of`, and `one_of` combine types, and
+[`LLM::Schema.to_s`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html#to_s-class_method)
+renders the schema as a prompt-friendly string. `required` and
+`defaults` refer to properties that already exist, so declare the
+property first and mark it afterwards.

data/docs/deepdive/fundamentals/tools.md

@@ -51,17 +51,17 @@ class Exec < LLM::Tool
 
   name "exec"
   description "run a command without a shell"
-  parameter :name, String, "the command's name"
-  parameter :arguments, Array[String], "command args"
-  required %i[name]
-  defaults arguments: [], timeout: 60, max_bytes: :max_bytes
+  parameter :arguments, Array[String], "a command and its arguments"
+  required %i[arguments]
+  defaults timeout: 60, max_bytes: :max_bytes
 
   def self.max_bytes(bytes = nil)
     bytes ? (@max_bytes = bytes) : (@max_bytes || 75_000)
   end
 
-  def call(name:, arguments: [], timeout: 60, max_bytes: self.class.max_bytes)
-    command = spawn(name:, arguments:, max_bytes:)
+  def call(arguments: [], timeout: 60, max_bytes: self.class.max_bytes)
+    name = arguments[0]
+    command = spawn(name:, arguments: arguments[1..], max_bytes:)
     wait(command:, timeout:)
     {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
   rescue LLM::Interrupt
@@ -172,33 +172,37 @@ matter what.
 If
 [`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
 raises, the runtime returns `{error: true, type: "RuntimeError",
-message: "boom"}` to the model. You can also rescue inside
-[`LLM::Tool#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#call)
-and return your own error shape that gives the model more context.
+message: "boom"}` to the model. A tool can also check for a known
+failure and return its own error shape, which gives the model
+more context than a generic error. The `exec` tool, for example,
+reports a missing command through `command.not_found?` rather than
+letting the spawn fail.
 
 ```ruby
 require "llm/tools/utils"
 
-class Exec < LLM::Tool
+class SafeExec < LLM::Tool
   include Utils
 
-  name "exec"
-  description "run a command without a shell"
-  parameter :name, String, "the command name"
-  parameter :arguments, Array[String], "command args"
-  required %i[name]
-  defaults arguments: [], timeout: 60, max_bytes: :max_bytes
+  name "safe-exec"
+  description "run a command and report a missing one"
+  parameter :arguments, Array[String], "a command and its arguments"
+  required %i[arguments]
+  defaults timeout: 60, max_bytes: :max_bytes
 
   def self.max_bytes(bytes = nil)
     bytes ? (@max_bytes = bytes) : (@max_bytes || 75_000)
   end
 
-  def call(name:, arguments: [], timeout: 60, max_bytes: self.class.max_bytes)
-    command = spawn(name:, arguments:, max_bytes:)
+  def call(arguments: [], timeout: 60, max_bytes: self.class.max_bytes)
+    name = arguments[0]
+    command = spawn(name:, arguments: arguments[1..], max_bytes:)
     wait(command:, timeout:)
-    {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
-  rescue Errno::ENOENT
-    {ok: false, error: "command not found: #{name}"}
+    if command.not_found?
+      {ok: false, error: "command '#{name}' was not found on this system"}
+    else
+      {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
+    end
   end
 end
 ```
@@ -207,8 +211,8 @@ end
 
 Custom error handling gives the model domain-specific detail that
 helps it recover. Instead of a generic "RuntimeError: boom", the
-model sees `{ok: false, error: "command not found: ls"}` and knows
-to correct the command name and try again.
+model sees `{ok: false, error: "command 'ls' was not found on this
+system"}` and knows to correct the command name and try again.
 
 #### Notes
 
@@ -244,8 +248,7 @@ class Exec < LLM::Tool
   set name: "exec",
       description: "run a command without a shell",
       parameters: [
-        [:name, String, "the command's name", {required: true}],
-        [:arguments, Array[String], "command args", {default: []}],
+        [:arguments, Array[String], "a command and its arguments", {required: true}],
         [:timeout, Integer, "timeout in seconds", {default: 60}],
         [:max_bytes, Integer, "max bytes to emit", {default: 75_000}]
       ]
@@ -254,8 +257,9 @@ class Exec < LLM::Tool
     bytes ? (@max_bytes = bytes) : (@max_bytes || 75_000)
   end
 
-  def call(name:, arguments: [], timeout: 60, max_bytes: self.class.max_bytes)
-    command = spawn(name:, arguments:, max_bytes:)
+  def call(arguments: [], timeout: 60, max_bytes: self.class.max_bytes)
+    name = arguments[0]
+    command = spawn(name:, arguments: arguments[1..], max_bytes:)
     wait(command:, timeout:)
     {ok: command.success?, stdout: command.stdout, stderr: command.stderr}
   end
@@ -326,6 +330,55 @@ loop, confirmation, and error handling behave identically. A single
 failing tool returns a structured error to the model, which can
 decide to retry or continue with the results it has.
 
+### Platform-native tools
+
+#### Overview
+
+Some capabilities live inside the provider rather than on your
+machine. Web search, code execution, file search, and computer use are
+examples: the provider runs them on its own infrastructure, and the
+model can call them directly. The runtime represents these with
+[`LLM::ServerTool`](https://r.uby.dev/api-docs/llm.rb/LLM/ServerTool.html).
+A server tool is not an
+[`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html)
+subclass, so it never appears in `LLM::Tool.subclasses`.
+
+#### How it works
+
+Build a server tool from a provider with
+[`LLM::Provider#server_tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#server_tool-instance_method),
+or read a ready-made one from the provider's catalog with
+[`LLM::Provider#server_tools`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#server_tools-instance_method).
+Pass server tools in the same `tools:` list as local tools:
+
+```ruby
+require "llm"
+
+llm = LLM.google(key: ENV["KEY"])
+ctx = LLM::Context.new(llm, tools: [llm.server_tool(:google_search)])
+ctx.talk "Summarize today's news"
+```
+
+Each provider defines its own catalog. OpenAI offers `web_search`,
+`file_search`, `image_generation`, `code_interpreter`, and
+`computer_use`; Google offers `google_search`, `code_execution`, and
+`url_context`; Anthropic offers `bash`, `web_search`, and
+`text_editor`.
+
+#### Why would I use it?
+
+A server tool saves you from building and hosting the capability
+yourself. Search, code execution, and file search run on the
+provider's side, so the model can call them without a local tool
+loop, a service of your own, or extra credentials.
+
+#### Notes
+
+OpenAI, Google, and Anthropic also expose a `web_search(query:)`
+method that performs a search in one call and returns the results. A
+server tool accepts whatever options the provider documents, for
+example `llm.server_tool(:web_search, max_uses: 5)` on Anthropic.
+
 ### Built-in tools
 
 #### Overview

data/docs/deepdive/media/audio.md

@@ -14,10 +14,7 @@ copy the result somewhere useful.
 #### How it works
 
 When you want to convert text to speech, call
-[`LLM::Audio#create_speech`](https://r.uby.dev/api-docs/llm.rb/LLM/Audio.html#create_speech).
-The provider returns an audio clip as a
-[`LLM::URIData`](https://r.uby.dev/api-docs/llm.rb/LLM/URIData.html)
-object. The generated audio can be copied
+`audio.create_speech`. The response holds the audio clip, which can be copied
 to a file or streamed directly. Each provider supports different
 output formats and voice options:
 
@@ -38,20 +35,14 @@ single method call.
 #### Notes
 
 OpenAI has full audio support. Google and DeepInfra have partial
-support. The
-[`LLM::Audio#create_speech`](https://r.uby.dev/api-docs/llm.rb/LLM/Audio.html#create_speech)
-method returns a
-[`LLM::URIData`](https://r.uby.dev/api-docs/llm.rb/LLM/URIData.html)
-object.
+support.
 
 ### Transcription
 
 #### Overview
 
-Transcription turns an audio file into text. Pass a file path
-to
-[`LLM::Audio#create_transcription`](https://r.uby.dev/api-docs/llm.rb/LLM/Audio.html#create_transcription)
-and get back the spoken content as
+Transcription turns an audio file into text. Pass a file path to
+`audio.create_transcription` and get back the spoken content as
 a string. OpenAI, Google, and DeepInfra support it. Transcribe
 meeting notes, voice memos, or podcast episodes for search and
 processing. The response is plain text you can feed into any
@@ -60,8 +51,8 @@ downstream pipeline.
 #### How it works
 
 When you want to transcribe audio into text, call
-[`LLM::Audio#create_transcription`](https://r.uby.dev/api-docs/llm.rb/LLM/Audio.html#create_transcription).
-The provider processes the audio and returns the transcribed text.
+`audio.create_transcription`. The provider processes the audio and
+returns the transcribed text.
 The file can be a local path or a URL depending on provider support:
 
 ```ruby
@@ -88,8 +79,7 @@ support.
 
 Translation transcribes audio and translates it into English in
 one step. Pass a file to
-[`LLM::Audio#create_translation`](https://r.uby.dev/api-docs/llm.rb/LLM/Audio.html#create_translation)
-and get back the
+`audio.create_translation` and get back the
 translated text. OpenAI and Google support it. Translate
 multilingual podcasts, interviews, or any audio where you need
 the content in English without running a separate translation
@@ -98,8 +88,7 @@ pipeline.
 #### How it works
 
 When you want to translate spoken audio into English, call
-[`LLM::Audio#create_translation`](https://r.uby.dev/api-docs/llm.rb/LLM/Audio.html#create_translation).
-The provider transcribes the spoken language and translates the
+`audio.create_translation`. The provider transcribes the spoken language and translates the
 result into English in a single operation. The returned text is the
 English translation:
 

data/docs/deepdive/media/images.md

@@ -14,11 +14,10 @@ requires no code changes.
 #### How it works
 
 The
-[`LLM::Images#create`](https://r.uby.dev/api-docs/llm.rb/LLM/Images.html#create)
-method sends a prompt to the provider and
-returns the result as a
-[`LLM::URIData`](https://r.uby.dev/api-docs/llm.rb/LLM/URIData.html)
-object. The same API works
+`images.create`
+method sends a prompt to the provider and returns an
+[`LLM::Response`](https://r.uby.dev/api-docs/llm.rb/LLM/Response.html)
+whose `images` array holds the generated images. The same API works
 across providers: swap
 [`LLM.openai`](https://r.uby.dev/api-docs/llm.rb/LLM.html#openai-class_method) for
 [`LLM.xai`](https://r.uby.dev/api-docs/llm.rb/LLM.html#xai-class_method) and the rest
@@ -61,11 +60,10 @@ text-to-image prompts, giving you iterative vector editing.
 #### How it works
 
 The
-[`LLM::Images#edit`](https://r.uby.dev/api-docs/llm.rb/LLM/Images.html#edit)
-method takes a prompt and an image path. It
-returns a modified image as a
-[`LLM::URIData`](https://r.uby.dev/api-docs/llm.rb/LLM/URIData.html)
-object. Copy the result
+`images.edit`
+method takes a prompt and an image path. It returns an
+[`LLM::Response`](https://r.uby.dev/api-docs/llm.rb/LLM/Response.html)
+whose `images` array holds the modified image. Copy the result
 to a file the same way you would with generated images.
 
 ```ruby

data/docs/deepdive/media/ocr.md

@@ -42,7 +42,5 @@ per page with markdown.
 #### Notes
 
 Only Mistral currently supports OCR through the llm.rb runtime.
-The response exposes pages through
-[`LLM::OCR::Response#pages`](https://r.uby.dev/api-docs/llm.rb/LLM/OCR/Response.html#pages),
-where each page
+The response exposes pages through its `pages` reader, where each page
 has a `markdown` field containing the extracted text.

data/docs/deepdive/reference/cost.md

@@ -107,3 +107,51 @@ The console renders context usage as a proportion, not a cost.
 returns a `Rational` of the tokens used over the context window
 (for example `Rational(100, 10_000)`), or `nil` when the window is
 unknown or the conversation is too short.
+
+### Token usage
+
+#### Overview
+
+[`LLM::Usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Usage.html)
+holds the token counts a provider reports for a request: input,
+output, reasoning, cache read, cache write, and the audio and image
+tokens where a model supports them. Cost is computed from it, and so
+is the console's context meter.
+
+#### How it works
+
+Every context and agent exposes four readers, each answering a
+different question:
+
+```ruby
+ctx.token_usage    # => LLM::Usage, summed over the whole conversation
+ctx.context_used   # => tokens in the most recent assistant message
+ctx.context_usage  # => Rational fraction of the context window in use
+ctx.context_window # => the model's window, or nil when unknown
+```
+
+[`LLM::Context#token_usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#token_usage-instance_method)
+accumulates across the conversation and returns `LLM::Usage.zero`
+before any provider usage has been recorded.
+[`LLM::Context#context_used`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#context_used-instance_method)
+is the live size of a single turn, which is what the context window
+is really being spent on.
+[`LLM::Context#context_window`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#context_window-instance_method)
+reads the limit from the model registry, and
+[`LLM::Context#context_usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#context_usage-instance_method)
+divides one by the other.
+
+#### Why would I use it?
+
+`token_usage` answers "what has this conversation cost so far", while
+`context_used` and `context_usage` answer "how much room is left".
+Showing both lets a user see spend and headroom without either number
+being mistaken for the other.
+
+#### Notes
+
+`LLM::Context#usage` is an alias of `token_usage`, kept for
+compatibility. `context_used` and `context_usage` return `nil` when
+the model is unknown to the registry, or before the conversation has
+an assistant message to measure. An agent delegates all four readers
+to the context it wraps.