llm.rb 15.1.0 → 15.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b496d3aec5a309af0ff9eaac32cabb6c7191bf2bac1f3b664c02a56c593402e
-  data.tar.gz: 0ae83d7794b4dad881de7b9866b3894746efa1853e349fc5707416e367802db5
+  metadata.gz: 8437f48c9a995054696648dfbe3386a5f0d8c8a62379765d2eca8694cf3adb3b
+  data.tar.gz: d2c36a69342e2fef94472abc25e813a0ee8bbef9aba15e68b275d89d307a6405
 SHA512:
-  metadata.gz: 9f890dd0720d0acbc79f9df2196f3595a68cd618fd0d09dc02fcab9a6fe27758ae72efd4b764614d5511bdb7914f586fba7194b3d1a5bec186562b9196753783
-  data.tar.gz: f25bc47b9bd5dcb0afea4f2ddbcb1ad37f74863cff962de6ceefa6157af073997589fd08fad0b2df11288aa24db41685127542b4d1748a71c4fef607d6b76ba2
+  metadata.gz: d1d120fe448ee693ba627cfdfe213cd42030fe8448f72c8cf6ecaddb62d2ac5f7b07ded6191142ec28571b41acbdf8c96b458420889e7fb75990f53f51b3ab43
+  data.tar.gz: 816b6feffe0339f52798062de3f36188b3d6574203289f450fd07de2e1e600b29aa956a8ba50947d3ae27540a4132222f3b31bb865784f88e24074388a852058

data/CHANGELOG.md

@@ -11,10 +11,335 @@
 </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.1
+
+Changes since `v15.2.0`.
+
+This release makes the agent count its tool budget across the whole turn
+and emit tool returns to the stream once that budget is spent, and lets
+`LLM::Function#cancel` carry extra return fields.
+
+### Agent
+
+* **agent: count the tool budget across the whole turn** <br>
+  [`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
+  now caps the tool calls a turn runs in total. A batch of calls is
+  spent as a batch, and a batch that would take the turn past its
+  budget is not run at all; once the budget is spent no tool call runs,
+  and the agent keeps sending its in-band advisory until the model
+  answers without requesting more tools. Previously the agent ran up to
+  the budget, then ran further batches after each advisory, so a turn
+  could run more tool calls than its budget allowed.
+
+* **agent: emit tool returns when the budget is spent** <br>
+  Fix a bug where, once a turn's tool budget was spent, the agent passed
+  its in-band returns to the model without emitting them to the stream.
+  The stream went silent, so a stream that tracked tool-call state left
+  the calls in the `call` state. The returns are now emitted through
+  [`LLM::Stream#on_tool_return`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_return-instance_method)
+  like any other tool return.
+
+### Function
+
+* **function: `LLM::Function#cancel` takes extra return fields** <br>
+  [`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel-instance_method)
+  now accepts keywords beyond `reason:` and merges them into the
+  [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+  it builds. `LLM::Function#budget_spent` now builds its return through
+  `cancel` instead of hand-rolling an error, so a budget-spent return is
+  marked `cancelled: true` and carries `action:` and `advice:` hints. A
+  callback that receives returns can now tell a cancellation apart from
+  an ordinary error.
+
+## 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 +348,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 +457,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 +1547,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 +2611,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.