llm.rb 15.1.0 → 15.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b496d3aec5a309af0ff9eaac32cabb6c7191bf2bac1f3b664c02a56c593402e
-  data.tar.gz: 0ae83d7794b4dad881de7b9866b3894746efa1853e349fc5707416e367802db5
+  metadata.gz: 5c55a3fa1151afad5720fc33bbe60a71feed5577242e53b4e8d4e2f9962a18ed
+  data.tar.gz: 3099ef73435ed6d91b003a40e2e5c195a82a8f631418b21e7c8cbce9088a5c76
 SHA512:
-  metadata.gz: 9f890dd0720d0acbc79f9df2196f3595a68cd618fd0d09dc02fcab9a6fe27758ae72efd4b764614d5511bdb7914f586fba7194b3d1a5bec186562b9196753783
-  data.tar.gz: f25bc47b9bd5dcb0afea4f2ddbcb1ad37f74863cff962de6ceefa6157af073997589fd08fad0b2df11288aa24db41685127542b4d1748a71c4fef607d6b76ba2
+  metadata.gz: 8e0d5dd6c98355412a31dcb638081ea9f0553725cbf30aa6598eed5d16cd6d4693b5edfae8c063625ee2f5198b342e9b11850897370404267d291ddae4d747fe
+  data.tar.gz: 25102554a840fee5046804d17ff91673793603b96ab9ae246a30b7d3192a792e9bd7e384d76ce20abf2d504910330202cb2d4aef0057c7875c1ce3866ccfe177

data/CHANGELOG.md

@@ -11,10 +11,295 @@
 </p>
 
 > Changelog <br>
-> a [r.uby.dev](https://r.uby.dev) project
+> [r.uby.dev](https://r.uby.dev) project
 
 ## What's next
 
+*No unreleased changes yet. Check back after the next release.*
+
+## v15.2.0
+
+Changes since `v15.1.0`.
+
+This release renames the REPL to `LLM::Console` (with `/keep` replacing
+`/compact`) and routes every shell-out tool through a shared, bounded
+`exec` runner. It also adds `LLM::Message#created_at`, the `LLM::Tracer`
+factory methods, a `bundle` tool, per-tool `max_bytes` output limits,
+and a `-v` switch to the CLI, and refreshes the model registry.
+
+### Core
+
+* **message: add `LLM::Message#created_at`** <br>
+  [`LLM::Message#created_at`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#created_at-instance_method)
+  returns the time the message was created, defaulting to the moment the
+  message is initialized. The timestamp is serialized into
+  [`LLM::Context#to_json`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_json-instance_method)
+  as an ISO-8601 string and restored on deserialization, so it can be
+  stored alongside the rest of the conversation.
+
+### Agent
+
+* **agent: inherit the ORM model's name** <br>
+  An `acts_as_agent` (ActiveRecord) or `plugin :agent` (Sequel) model now
+  names its generated
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) after
+  the model class. Previously the agent was an anonymous subclass, so
+  without an explicit name it defaulted to a gibberish `#<Class:0x...>`
+  string. The wrapper now initializes the agent's name before `.agent`
+  returns, and
+  [`LLM::Agent.name`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#name-class_method)
+  kebab-cases a `Class` argument, so an `AdminUser` model yields an agent
+  named `admin-user`.
+
+### Cli
+
+* **cli: add a `-v` switch** <br>
+  `bin/llm.rb` gains a `-v` switch that prints the version (`llm.rb v#{LLM::VERSION}`) and exits.
+
+### Console
+
+* **console: raise `LLM::Interrupt` on the agent's thread** <br>
+  Pressing Esc to cancel now also raises `LLM::Interrupt` on the agent's
+  thread. `LLM::Agent#cancel!` alone can be a no-op at some stages of the
+  request lifecycle, so the console backs it up by interrupting the thread
+  that runs the agent.
+
+* **console: add a `/keep` command and retire `/compact`** <br>
+  The console now offers `/keep` for freeing space in the context window;
+  the `/compact` command is removed. `/keep` takes the same argument, so
+  `/keep 20%` keeps 20% of the context window. Closes
+  [issue #161](https://github.com/r-uby-dev/llm.rb/issues/161).
+
+* **console: keep the UI responsive during long streams** <br>
+  A model can emit many chunks in a single turn. The console now draws
+  at most four streamed chunks at a time, then checks for input, so the
+  UI stays responsive even when a turn produces a large amount of
+  output.
+
+* **console: persist the conversation when a turn is done** <br>
+  The console now saves the agent's state after the turn finishes,
+  rather than while the response is still streaming. State is still
+  saved every turn, but not until the turn has completed.
+
+* **console: render markdown text as typed** <br>
+  Fix a bug where [`LLM::Console::Markdown`](https://r.uby.dev/api-docs/llm.rb/LLM/Console/Markdown.html)
+  mangled the model's output: HTML could render invisible, and
+  sequences like `...` were converted to unicode glyphs. The renderer
+  now uses a custom kramdown parser that disables the HTML, smart-quote,
+  and typographic-symbol parsers, so tags and punctuation come through
+  exactly as written.
+
+* **console: fix a crash in the markdown parser** <br>
+  Fix a bug where the markdown renderer raised an error on an unclosed
+  HTML tag or a partial tag taken out of context, such as `4 < 5`. The
+  parser now emits the `<...` run literally when there is no closing
+  `>`, so the text renders instead of crashing.
+
+* **console: stop rendering bare pipes as tables** <br>
+  Fix a bug where the markdown renderer treated a lone `|foo|` in prose
+  as a table and mangled its output. A pipe line now parses as a table
+  only when a header row is followed by a delimiter row, so bare pipes
+  come through literally while real tables still render.
+
+* **console: find the worker thread when cancelling** <br>
+  Fix a bug where pressing Esc to cancel raised `LLM::Interrupt` on an
+  instance variable that does not exist, so the interrupt was a no-op and
+  a cancel could leave the turn running. The console now resolves the
+  worker thread through its `#thread` reader and interrupts it.
+
+* **console: protect the state write from cancellation** <br>
+  The console now defers `LLM::Interrupt` while it saves the agent's
+  state after a turn, so a cancel that arrives during the write cannot
+  interrupt `agent.save` mid-flight and risk a lost or corrupted session
+  file.
+
+### Tools
+
+* **tools: the command runner is now `exec`** <br>
+  The command tool that spawns a process without a shell is now
+  [`LLM::Tool::Exec`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Exec.html),
+  with the tool name `exec` instead of the previous `shell`. This is an
+  internal refactor of the shell-out tools: `git`, `rg`, `mkdir`,
+  `ruby`, and `bundle` all route through it and inherit
+  its bounded output.
+
+* **tools: report when a command cannot be found** <br>
+  `LLM::Tool::Exec` now returns `{ok: false, error: "command 'NAME' was
+  not found on this system"}` when the requested command is missing,
+  instead of a bare `{ok: false}` result that did not tell the model why
+  the tool failed.
+
+* **tools: drop the `name:` parameter from `LLM::Tool::Exec#call`** <br>
+  `LLM::Tool::Exec#call` now takes a single `arguments:` array instead of
+  separate `name:` and `arguments:` parameters, with the command name as
+  the first element (for example `arguments: ["rg", "-m", "10", "lib"]`).
+  The `Git`, `Mkdir`, `Rg`, `Ruby`, and `Bundle` tools build their calls
+  the same way. The change was made after models were observed confusing
+  the two parameters, so a single list is simpler and more reliable.
+
+* **tools: rename `repl` as `console`** <br>
+  The interactive loop is renamed to
+  [`LLM::Console`](https://r.uby.dev/api-docs/llm.rb/LLM/Console.html),
+  which better reflects what it does. `agent.console` is the primary
+  entry point, and the require path moves from `llm/repl` to
+  `llm/console`. Backwards-compatible aliases remain: `LLM::Repl`,
+  `LLM::Agent#repl`, the ORM wrappers' `#repl`, and `LLM::Command =`
+  `LLM::Console::Command`.
+
+* **tools: `LLM::Tool::Git#call` takes an `arguments:` array** <br>
+  [`LLM::Tool::Git#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Git.html)
+  now takes a single `arguments:` array in place of the previous
+  `subcommand:` parameter. The first element must be one of `log`,
+  `diff`, `commit`, `checkout`, `branch`, or `show`, validated before the
+  command is spawned; the remaining elements are forwarded to git.
+
+* **tools: `LLM::Tool::Utils` now owns command spawning** <br>
+  The shared [`LLM::Tool::Utils`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Utils.html)
+  module now requires the `test-cmd.rb` gem (at `~> 2.7.1`) itself and
+  exposes the `spawn` and `wait` helpers, so any tool that includes
+  `Utils` gets command spawning without requiring `exec` directly. The
+  `Git`, `Mkdir`, `Rg`, `Ruby`, `Exec`, and `Bundle` tools all
+  inherit their bounded-output protections from this shared runner.
+
+* **tools: route `git`, `rg`, `mkdir`, and `ruby` through `exec`** <br>
+  `LLM::Tool::Git`, `LLM::Tool::Rg`, `LLM::Tool::Mkdir`, and
+  `LLM::Tool::Ruby` now implement their calls through the `exec` tool,
+  completing the refactor so every tool that shells out flows through
+  the shared command runner with its bounded output.
+
+* **tools: read-file returns structured lines** <br>
+  `LLM::Tool::ReadFile#call` now returns its content as structured
+  `{lineno:, content:}` lines under a `lines:` key instead of a single
+  `content:` string, and adds a `truncated:` flag. A reversed range
+  (`start: 20, stop: 2`) is swapped to read lines 2 through 20. The
+  truncation marker is kept out of the returned lines, so the model
+  does not mistake it for a real file line.
+
+* **tools: write-file appends a trailing newline by default** <br>
+  `LLM::Tool::WriteFile` now ensures written content ends with a newline,
+  adding one when the content does not already end with `\n`. It previously
+  wrote the content exactly as given. A new `newline:` parameter (default
+  `true`) controls this, so `newline: false` writes the content exactly as
+  given.
+
+* **tools: fix `edit-file` treating `before` as a regex** <br>
+  `LLM::Tool::EditFile` now escapes the `before` snippet with
+  `Regexp.escape`, so regex metacharacters are matched literally, and
+  switches to the block form of `sub` so the `after` replacement keeps
+  backslash sequences like `\1` and `\&` literal.
+
+* **tools: bound tool output with a per-tool `max_bytes`** <br>
+  Each of the `Exec`, `ReadFile`, `Rg`, `Mkdir`, `Ruby`, and
+  `Bundle` tools gains a `max_bytes` limit (default 75,000) for the
+  maximum number of bytes a tool returns to the model. `Exec` and
+  `ReadFile` add the class-level `max_bytes` accessor, which the other
+  tools inherit through `Exec`, so each tool's cap can be configured
+  independently, for example `LLM::Tool::ReadFile.max_bytes(175_000)`.
+  It does not enforce the limit by itself;
+  [`LLM::Tool::Utils#truncate`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Utils.html#truncate-instance_method)
+  trims a string within the limit and marks the trailing content as
+  truncated, and `truncate!` returns a `[content, truncated]` tuple for
+  callers that structure truncated output themselves. `rg` also gains a
+  `max_count:` parameter that caps the number of results per file.
+
+* **tools: add a `bundle` tool** <br>
+  A new [`LLM::Tool::Bundle`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Bundle.html)
+  tool runs a command through `bundle`. It uses the `BUNDLE_GEMFILE`
+  environment variable when set, or a `Gemfile` in the current working
+  directory otherwise. The tool takes an `arguments:` array, so the
+  model passes the bundle command and its arguments as a single list,
+  for example `arguments: ["exec", "rspec"]`.
+
+* **tools: resolve defaults through `LLM::Utils.resolve_option`** <br>
+  A tool parameter default can now be an immediate value, a Symbol resolved
+  as a method on the tool, or a Proc evaluated lazily at runtime, matching
+  how `LLM::Agent` resolves its attributes. This lets a default track a
+  value that can change between boot and runtime, such as a tool's
+  `max_bytes`.
+
+### Registry
+
+* **refresh model metadata** <br>
+  Update `data/` with current pricing, limits, and capabilities for the
+  OpenRouter, OpenAI, Bedrock, DeepInfra, DeepSeek, Google, Mistral,
+  Moonshot, Z.ai, and Alibaba registries.
+
+### Provider
+
+* **provider: retry `Net::WriteTimeout`, too** <br>
+  Requests that raise `Net::WriteTimeout` are now retried alongside the
+  other timed-out and rate-limited requests, up to the `retry_budget`,
+  matching how `Net::OpenTimeout` and `Net::ReadTimeout` are handled. The
+  console status bar also reports a write timeout as `Timed out`.
+
+* **alibaba: default to a retry budget of 8** <br>
+  An agent that runs on the Alibaba provider now defaults to a retry
+  budget of 8 instead of 5, because Alibaba (token plan) frequently rate
+  limits and times out requests that it later recovers from. An explicit
+  `retry_budget:` still overrides the default.
+
+* **deepseek: default to the `deepseek-flash` model** <br>
+  The default DeepSeek chat model is now `deepseek-flash` instead of
+  `deepseek-v4-flash`. DeepSeek resolves `deepseek-flash` to
+  `deepseek-v4.1-flash` and recommends the name in its documentation and
+  API error messages, so the default follows the current model alias
+  instead of a pinned version.
+
+### Tracer
+
+* **tracer: add `LLM::Tracer` factory methods** <br>
+  Add
+  [`LLM::Tracer.logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#logger-class_method),
+  [`LLM::Tracer.pretty_logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#pretty_logger-class_method),
+  and
+  [`LLM::Tracer.telemetry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#telemetry-class_method)
+  as the preferred way to build a tracer for a provider, so switching
+  between tracers means changing a factory method instead of a class name.
+  The old `LLM.logger(llm, ...)` convenience method is removed in favor
+  of `LLM::Tracer.logger(llm, ...)`.
+
+* **tracer: add `path:` support to `LLM::Tracer::PrettyLogger`** <br>
+  [`LLM::Tracer::PrettyLogger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html)
+  now accepts a `path:` option to write its human-readable entries to a
+  file, matching `LLM::Tracer::Logger`. It previously only accepted `io:`.
+
+### Fix
+
+* **json: scrub invalid UTF-8 on dump** <br>
+  Fix a bug where [`LLM::JSONAdapter`](https://r.uby.dev/api-docs/llm.rb/LLM/JSONAdapter.html)
+  raised a JSON generator error when dumping a string tagged as UTF-8 that
+  carried invalid bytes. The normalize step now transcodes every string to
+  valid UTF-8, replacing invalid sequences with the replacement character,
+  so dumping works on `json ~> 3.0`. The `oj` and `yajl` adapters now run
+  the same normalization, so every backend scrubs invalid bytes before
+  serializing.
+
+* **fork: require xchan.rb `~> 0.23`** <br>
+  The `:fork` concurrency strategy now requires the `xchan.rb` gem at
+  `~> 0.23` instead of `~> 0.22`. xchan.rb 0.23.0 replaces the external
+  `lockf.rb` gem with a built-in, Fiddle-based `Chan::Lockf`, so fork
+  channels no longer carry that extra dependency. (The socket
+  length-header deadlock fix shipped earlier, in xchan.rb 0.22.0.)
+
+* **async: fix a shutdown exception on the reactor thread** <br>
+  Fix a bug where the `:async` strategy's
+  [`LLM::Function::Async::Reactor`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Async/Reactor.html)
+  raised a `TypeError` on shutdown with recent `async` and `io-event`
+  versions, because their internals tried to raise an integer as an
+  exception. The scheduler is now detached from the reactor thread
+  before it exits, which avoids that code path entirely, and teardown
+  is managed by `reactor.stop`, so the thread exits promptly instead of
+  abruptly or hanging.
+
+* **openai: prevent the loss of user messages in the completions path** <br>
+  Fix a bug where the request body was built from `params[:messages]`
+  alone when that key was present, discarding the messages built from the
+  prompt. The DeepSeek and Alibaba schema support injects the schema
+  system message into `params[:messages]`, so a request with a `schema:`
+  could be sent with the schema message only, dropping the user's
+  messages. The built messages now lead with `params[:messages]`, and the
+  key is removed before the body is assembled.
+
 ## v15.1.0
 
 Changes since `v15.0.3`.
@@ -23,7 +308,7 @@ This release adds the OpenRouter provider, splits provider timeouts
 into `connect_timeout` and `read_timeout`, retries timed-out requests,
 and renames `on_rate_limit` to `on_retry`. Skills now gain a
 frontmatter `model:` parameter and inherit the parent agent's model,
-while the CLI gains `-m` and `-x` switches, and the REPL shows retry
+while the CLI gains `-m` and `-x` switches, and the console shows retry
 progress and measures text by display width.
 
 ### Provider
@@ -132,21 +417,21 @@ progress and measures text by display width.
   up to three stack lines from the backtrace, so the failure is easier to
   locate and report than a bare diagnostic.
 
-### Repl
+### Console
 
-* **repl: show retry progress in the status bar** <br>
-  When a request is rate limited or times out, the curses-based REPL status
+* **console: show retry progress in the status bar** <br>
+  When a request is rate limited or times out, the curses-based console status
   bar shows a retry indicator with the error and the remaining attempts, for
   example `🔁 Rate limited • attempt 2 of 5`.
 
-* **repl: measure text width with `unicode-display_width`** <br>
-  The curses-based REPL now counts and slices text by display column width
+* **console: measure text width with `unicode-display_width`** <br>
+  The curses-based console now counts and slices text by display column width
   instead of character count, so wrapping, table columns, and clipping stay
   aligned for wide characters such as emoji. It requires the optional
   `unicode-display_width` gem.
 
-* **repl: treat `LLM::InsufficientQuotaError` as a rate limit in the status bar** <br>
-  The curses-based REPL status bar now shows `Rate limited` when a request
+* **console: treat `LLM::InsufficientQuotaError` as a rate limit in the status bar** <br>
+  The curses-based console status bar now shows `Rate limited` when a request
   raises
   [`LLM::InsufficientQuotaError`](https://r.uby.dev/api-docs/llm.rb/LLM/InsufficientQuotaError.html),
   matching how ordinary `LLM::RateLimitError`s are shown, instead of falling
@@ -1222,7 +1507,7 @@ reliable across all six concurrency backends. The `functions` and
   `LLM.require` now accepts a second `version` parameter that is passed
   to `Kernel#gem` before loading, enabling version constraints for
   optional runtime dependencies. For example,
-  `LLM.require "test-cmd.rb", "~> 2.1"` ensures a minimum gem version
+  `LLM.require "test-cmd.rb", "~> 2.2"` ensures a minimum gem version
   is available. This is used internally by the `Git`, `Rg`, `Mkdir`,
   and `Shell` tools to enforce compatibility with the `test-cmd.rb` gem.
 
@@ -2286,7 +2571,7 @@ As always, see the changelog details for a thorough overview.
 * **Add `LLM::Agent#repl`** <br>
   Add a curses-based read-eval-print loop for `LLM::Agent` that lets
   developers interact with an agent after it has been set up or has
-  performed a task. It is similar to `binding.pry`: once you exit,
+  performed a task. It is similar to `binding.irb`: once you exit,
   you can continue with the rest of your program. It requires the
   `curses` gem.
 

data/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <a href="https://r.uby.dev">
     <img
-      src="https://github.com/r-uby-dev/llm.rb/raw/main/rubydev.svg"
+      src="rubydev.svg"
       width="400"
       height="200"
       border="0"
@@ -10,16 +10,14 @@
   </a>
 </p>
 
-> A [r.uby.dev](https://r.uby.dev/llm) project.
+> [r.uby.dev](https://r.uby.dev/llm) project.
 
 Welcome to the canonical llm.rb repository.
 
 llm.rb is an advanced runtime for building agentic AI applications
 on CRuby. It has zero runtime dependencies by default, supports
 concurrent and parallel tool execution and has a single coherent API
-that spans 14+ providers. Streaming, tools, guards, compaction, the
-REPL, builtin MCP/A2A support and the database integrations all build
-on the same three concepts: providers, contexts, and agents.
+that spans 14+ providers.
 
 The easiest way to learn about llm.rb is to ask [the r.uby.dev chatbot](https://r.uby.dev)
 a question. It is connected to the llm.rb GitHub repository, backed by
@@ -206,7 +204,7 @@ isolation from its parent.
 
 A couple of concurrency strategies require optional, opt-in dependencies.
 The `async` strategy requires the [async](https://github.com/socketry/async)
-gem and the `fork` strategy requires the [xchan.rb](https://github.com/0x1eef/xchan.rb)
+gem and the `fork` strategy requires the [xchan.rb](https://github.com/r-uby-dev/xchan.rb)
 gem. The `fiber` strategy requires a scheduler (`Fiber.scheduler`) but by
 default Ruby does not provide one.
 
@@ -247,27 +245,25 @@ end
 ```
 </details>
 <details>
-<summary>Console (<code>binding.pry</code> for agents)</summary>
+<summary>Console (<code>binding.irb</code> for agents)</summary>
 <br>
 
-The [LLM::Agent#repl](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
-method drops you into a highly capable read-eval-print loop (REPL)
+The [LLM::Agent#console](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#console-instance_method)
+method drops you into a highly capable interactive console
 that is built on top of curses. It can help you debug agents,
 test your tools, connect to MCP servers, and even A2A agents.
-The REPL stands out because it connects to the surrounding
+The console stands out because it connects to the surrounding
 runtime and it can be extended by your code. Think of it as
-`binding.pry` but for agents.
+`binding.irb` but for agents.
 
 ##### Demo
 
-[Watch in high quality on asciinema](https://asciinema.org/a/OsS8wwaasKasoDDz)
-
-![llm.rb REPL demo](demo.gif)
+![llm.rb console demo](demo.gif)
 
 
 ##### Installation
 
-The REPL is distributed with llm.rb so you don't have to install
+The console is distributed with llm.rb so you don't have to install
 a separate gem but it requires a number of optional dependencies
 to be installed separately. The following gems provide the full
 experience:
@@ -276,8 +272,8 @@ experience:
 
 ##### Persistence
 
-The `path:` option can be set on an agent for automatic persistence
-across REPL sessions. The `tools:` option attaches extra tools
+the `path:` option can be set on an agent for automatic persistence
+across console sessions. The `tools:` option attaches extra tools
 for the duration of the session. Recall previous turns with Ctrl+P and
 Ctrl+N.
 
@@ -287,21 +283,26 @@ require "llm/tools"
 
 llm = LLM.deepseek(key: ENV["KEY"])
 agent = LLM::Agent.new(llm, name: "my-agent", path: "agent.json")
-agent.repl(tools: LLM::Tool.subclasses)
+agent.console(tools: LLM::Tool.subclasses)
 ```
 
 ##### CLI
 
 The `llm.rb` executable is available on your PATH after installation.
-It starts a REPL session from any directory.The CLI auto-detects your
+It starts a console session from any directory. The CLI auto-detects your
 provider from standard environment variables (`DEEPSEEK_API_KEY`,
 `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.). Persistent sessions are
 stored under `~/.llm.rb/` and restored automatically on your next visit.
 
 ```bash
-llm.rb                     # auto-detect from $DEEPSEEK_API_KEY
+llm.rb                     # auto-detect from $PROVIDER_API_KEY
 llm.rb -p openai           # use OpenAI explicitly
+llm.rb -m gpt-5.6          # use a model other than the provider default
+llm.rb -c thread           # run tool calls on a separate thread
+llm.rb -n curb             # use libcurl as the HTTP transport
+llm.rb -x 900              # read timeout of 15 minutes
 llm.rb -t                  # temporary session, no persistence
+llm.rb -v                  # print the version
 ```
 </details>
 <details>
@@ -423,8 +424,8 @@ agent = Raven.find(agent.id).tap(&:research_codebase)
 ##
 # Start an agent console.
 # Query agent's state, debug, etc.
-# The REPL does not persist back to the database.
-agent.repl
+# The console does not persist back to the database.
+agent.console
 ```
 </details>
 
@@ -534,15 +535,15 @@ the call, or `nil` to let it run:
 ```ruby
 class PolicyGuard < LLM::Guard
   def call(function:)
-    if function.name == "shell"
+    if function.name == "exec"
       function.return(error: true, type: "policy_error",
-                      message: "shell is disabled")
+                      message: "exec is disabled")
     end
   end
 end
 
 llm = LLM.deepseek(key: ENV["KEY"])
-agent = LLM::Agent.new(llm, tools: [Shell, ReadFile], guard: PolicyGuard)
+agent = LLM::Agent.new(llm, tools: [LLM::Tool::Exec, ReadFile], guard: PolicyGuard)
 ```
 </details>
 
@@ -629,21 +630,28 @@ agent.talk "Hello"
 <summary>Observability</summary>
 <br>
 
-Trace what an agent is doing by attaching a tracer. Hook into
-requests, tool calls, and other runtime events to debug a
-misbehaving agent, monitor latency, or export spans to an
-observability backend. All built-in tracers share one interface,
-so switching between them means changing a class name:
+It is possible to trace what an agent is doing by attaching a
+tracer. A tracer can hook into requests, tool calls, and other
+runtime events to debug an agent, provide insights, monitor latency,
+or export spans to an observability backend. All built-in tracers
+share one interface, so switching between them means changing a
+factory method:
 
-* [`LLM::Tracer::PrettyLogger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html): human-readable single-line logs to stderr, ideal during development.
-* [`LLM::Tracer::Telemetry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Telemetry.html):
+* [`LLM::Tracer.pretty_logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#pretty_logger-class_method): human-readable single-line logs to stderr, ideal during development.
+* [`LLM::Tracer.telemetry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#telemetry-class_method):
 exports spans via OTLP for OpenTelemetry in production.
-* [`LLM::Tracer::Logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Logger.html):
+* [`LLM::Tracer.logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#logger-class_method):
 structured JSON to stdout or a file.
 
+It is also possible to create your own tracer by creating a subclass
+of [`LLM::Tracer`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html)
+that implements a number of callbacks that cover an agent's lifecycle.
+The tracer feature provides visibility into what the runtime is doing,
+and the tracer API lets other code hook into that feature.
+
 ```ruby
 llm = LLM.deepseek(key: ENV["KEY"])
-agent = LLM::Agent.new(llm, tracer: LLM::Tracer::PrettyLogger.new(llm))
+agent = LLM::Agent.new(llm, tracer: LLM::Tracer.pretty_logger(llm))
 agent.talk "Hello"
 ```
 </details>
@@ -668,7 +676,7 @@ class Agent < LLM::Agent
   set name: "sysadmin",
       description: "system administration agent",
       model: "deepseek-v4-pro",
-      tools: [LLM::Tool::Shell]
+      tools: [LLM::Tool::Exec]
 end
 
 llm = LLM.deepseek(key: ENV["KEY"])
@@ -756,7 +764,7 @@ require "llm"
 
 llm      = LLM.openai
 registry = llm.registry                # => LLM::Provider#registry
-cheapest = registry.models.sort.first  # => LLM::Model
+cheapest = registry.models.sort.first  # => LLM::Registry::Model
 cheapest.id                            # => "text-embedding-3-small"
 cheapest.context_window                # => 8191
 cheapest.structured_output?            # => false
@@ -895,6 +903,17 @@ IO.copy_stream res.images[0], "rocket-with-dog.svg"
 
 ## FAQ
 
+<details>
+<summary>Where can I see llm.rb in action?</summary>
+<br>
+<p>
+
+The [r.uby.dev](https://r.uby.dev) website is powered
+by llm.rb and its builtin MCP feature. It is connected
+to this very GitHub repository. It is designed to help
+you learn and troubleshoot llm.rb.
+</p>
+</details>
 <details>
 <summary>What about local LLM support?</summary>
 <br>
@@ -962,7 +981,7 @@ than three years and over that time multiple other
 contributors have contributed to llm.rb as well. New
 contributors are always welcome.
 
-I use the repl that is distributed with llm.rb to build
+I use the console that is distributed with llm.rb to build
 llm.rb itself so there is a healthy feedback loop and
 llm.rb has also been battle tested in production
 environments.
@@ -975,13 +994,19 @@ I am constantly focused on improving llm.rb by using
 it as my primary driver for development.
 </details>
 
-## Resources
+## See also
+
+The [roda-llm](https://github.com/r-uby-dev/roda-llm#readme) project
+is how I deploy multiple ActiveRecord-backed llm.rb agents over HTTP.
+Each agent has an identical interface at a unique path that provide
+CRUD operations and stream support (via SSE - Server Side Events).
+It lets you focus on implementing agents rather than the glue that
+brings them together. It is implemented as a Roda plugin that could
+be hosted within a Rails application or other Rack-based applications.
 
-The [r.uby.dev chatbot](https://r.uby.dev) is connected
-to this very GitHub repository. It can read documentation,
-source code, issues, and pull requests. The [docs/](docs/)
-directory contains the full documentation and the chatbot
-can find the answers to your questions there.
+The [docs/](docs/) directory contains the full documentation and
+the chatbot can find the answers to your questions there. Or you
+can read them yourself.
 
 ## License
 

data/bin/llm.rb

@@ -42,6 +42,10 @@ def wrap(text, width)
   end
 end
 
+def version
+  warn "llm.rb v#{LLM::VERSION}"
+end
+
 def help
   prog = File.basename($PROGRAM_NAME)
   warn ""
@@ -54,6 +58,7 @@ def help
   warn "  -n TRANSPORT   HTTP transports - net-http (default), net-http-persistent, and curb"
   warn "  -x TIMEOUT     The default read timeout (in seconds)"
   warn "  -t             Temporary session that doesn't persist to disk"
+  warn "  -v             Print version information"
   warn "  -h             Show this help"
   warn ""
   warn "Examples:"
@@ -74,12 +79,12 @@ def loaderror(ex)
   warn ""
   warn_title "Missing dependency: #{gem}"
   warn ""
-  warn "     The repl needs this gem, but it's not installed."
+  warn "     The console needs this gem, but it's not installed."
   warn ""
   wrapped "Fix:  gem install #{gem}", "     "
   wrapped "Or:   bundle add #{gem}", "     "
   warn ""
-  warn "     Tip:  If you don't need the repl, you can use the"
+  warn "     Tip:  If you don't need the console, you can use the"
   wrapped "library directly with:  require \"llm\"", "           "
   warn ""
   warn "  ───────────────────────────────────────────────────────"
@@ -120,7 +125,7 @@ def main(argv)
   # Make sure the dependencies are satisified first
   begin
     require "llm/tools"
-    require "llm/repl"
+    require "llm/console"
   rescue LLM::LoadError => ex
     loaderror(ex)
     exit 1
@@ -135,6 +140,9 @@ def main(argv)
       when '-h'
         help
         exit 0
+      when '-v'
+        version
+        exit 0
       when '-t'
         temp = true
       when '-c'
@@ -249,7 +257,7 @@ def main(argv)
     concurrency ||= :sequential
     path  = temp ? nil : data[Dir.getwd]
     agent = LLM::Agent.new(llm, model:, path:, concurrency:, tools: LLM::Tool.subclasses)
-    agent.repl
+    agent.console
   rescue Interrupt
     warn "llm.rb: Bye!"
   rescue => ex