llm.rb 12.6.0 → 13.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1660ea34a112d4c31eb8c9a51000ecd244b0f5629a4f763eceecd734d96f765b
-  data.tar.gz: 8040eefe13ffc48a40181642dad749d6abd7d16950f5d9e379ef006a0bb5af0c
+  metadata.gz: bb5c6136080e0136309987a4e042e6f646c26de39e38d6422bb3904fc665bf5f
+  data.tar.gz: d832b9c19f4173ba6e5631ffdc57f495eb4a9a8fb0b657801de185707bc4085e
 SHA512:
-  metadata.gz: cc1821c04eb0f996ca3e5d86d1722565e1fe2bc13351f3771c57de556d7ee9e97d930b3516ec70dea9686fad6443498c40d50584c6065a95242318f054a98d83
-  data.tar.gz: 3cc468ef1332c6f39d6b34a6a11fafe91eaf459ed80d5e79709f8106278fcb6fa1ba4f67b701a38539c3cba4d6967ad88858cccb4bb6b5b12690290036ad2afb
+  metadata.gz: 7ba4417a8c5b48a28b2baf04a2960374eae28c44dc2ec19e8f79da9a95f75fdf8cb5f1c749e6bfa1b1f6d1c790723e2005cb576f94f118997bb5e8b0f5d53a63
+  data.tar.gz: 0105af6bcaaec50930546e3a5a7207b8cf65e30bbea33359784061159748a3e2f3afb6e2b599eaad904e0c477d9827bb444c698315e56d43572be6ba86fe98b8

data/CHANGELOG.md

@@ -15,11 +15,569 @@
 
 ## What's next
 
+*No unreleased changes yet. Check back after the next release.*
+
+## v13.1.0
+
+Changes since `v13.0.0`.
+
+This release adds `LLM::Agent` class DSL attributes (`path`, `description`),
+extends skills with file-path loading and the `tools: all` directive, adds new
+built-in tools (`LLM::Tool::Ruby`, `LLM::Tool::EditFile`), introduces the
+`LLM::Tracer::PrettyLogger` for human-readable tracing, renames `Transcript`
+to `Buffer` across the REPL, ships a `bin/llm.rb` CLI entry point, and fixes
+several agent and tool bugs around persistence, interruption, and naming.
+
+### Core
+
+* **add post install message with deepdive link** <br>
+  The gemspec now includes a `post_install_message` that points users to
+  the deepdive guide at `https://r.uby.dev/llm/deepdive` after installation,
+  making it easier for new users to discover the project documentation.
+
+### Agent
+
+* **add `description` class DSL and instance method** <br>
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) now
+  has a `description` class DSL (`description "release engineer"`) and a
+  corresponding `#description` instance method. The description is an
+  optional self-documenting string that serves as a brief summary of the
+  agent's purpose. It can be set via the class DSL,
+  `LLM::Agent.set(description: ...)`, or `LLM::Agent.new(description: ...)`.
+
+* **add `path` class DSL and instance method** <br>
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) now
+  has a `path` class DSL (`path "contexts/admin.json"`) and a
+  corresponding `#path` instance method. When a path is set, the agent
+  automatically restores its conversation history from that file on
+  initialization and saves it back after each `talk` or `ask` turn,
+  making session persistence across process restarts transparent.
+
+### Skills
+
+* **accept a path to a markdown file** <br>
+  [`LLM::Skill.load`](https://r.uby.dev/api-docs/llm.rb/LLM/Skill.html#load-class_method)
+  now accepts a path to a markdown file in addition to a directory path.
+  When given a file path, the file is read directly instead of looking for
+  a `SKILL.md` inside a directory. This makes it possible to load a single
+  markdown file as a skill without placing it in a dedicated directory.
+
+* **extend with `all` keyword for loading the full tool registry** <br>
+  `LLM::Skill` now supports `tools: all` (or `tools: "*"`) in the frontmatter
+  to load all tools from the global
+  [`LLM::Tool.registry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#registry-class_method).
+  Previously, the `tools:` frontmatter only accepted `inherit`, an array of tool
+  names, or nothing. The new `all` keyword makes it possible to give a skill
+  access to every registered tool without listing them individually.
+
+### Tools
+
+* **add `LLM::Tool::Ruby` for executing Ruby code in a subprocess** <br>
+  [`LLM::Tool::Ruby`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Ruby.html)
+  is a new built-in tool that runs a string of Ruby code in a separate
+  Ruby process with a configurable timeout (default 15s). The code runs
+  in an isolated address space unaware of its parent, making it useful
+  for safe(ish) dynamic code execution. It must be required explicitly
+  with `require "llm/tools/ruby"` and requires the `test-cmd.rb` gem.
+
+* **rename `LLM::Tool::SwapText` to `LLM::Tool::EditFile`** <br>
+  The `SwapText` tool has been renamed to
+  [`LLM::Tool::EditFile`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/EditFile.html)
+  to better match the naming of sibling tools (`ReadFile`, `WriteFile`).
+  The old `require "llm/tools/swap_text"` path no longer exists; use
+  `require "llm/tools/edit-file"` instead.
+
+### Tracer
+
+* **add `LLM::Tracer::PrettyLogger` for human-readable tracing** <br>
+  [`LLM::Tracer::PrettyLogger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html)
+  is a new tracer that writes human-readable request and tool-call logs to a
+  console or file. Unlike the structured JSON output of
+  `LLM::Tracer::Logger`, the pretty logger emits single-line entries with
+  inline context, making it easier to follow agent activity at a glance.
+  It writes to `$stderr` by default and accepts an `io:` option for file
+  output.
+
+### Repl
+
+* **rename `LLM::Repl::Transcript` to `LLM::Repl::Buffer`** <br>
+  `LLM::Repl::Transcript` has been renamed to
+  [`LLM::Repl::Buffer`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Buffer.html)
+  to better reflect its role as a conversation state manager. The old
+  `start` and `finish` methods have been renamed to `open` and `close`
+  respectively. The public accessor on
+  [`LLM::Repl`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl.html) has been
+  renamed from `transcript` to `buffer`.
+
+* **add `write_message` for formatted message writing** <br>
+  [`LLM::Repl::Buffer#write_message`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Buffer.html#write_message-instance_method)
+  and
+  [`LLM::Repl#write_message`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl.html#write_message-instance_method)
+  provide a convenience method that takes a username and content string,
+  formatting the output with a bold `user:` label and a trailing newline.
+  This is simpler than the equivalent sequence of `write` calls.
+
+* **add `Command#write_message` and refactor `Command#write`** <br>
+  [`LLM::Command#write_message`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Command.html#write_message-instance_method)
+  provides a convenience method that takes a username and content string,
+  matching the same interface on `LLM::Repl` and `LLM::Buffer`. The
+  `Command#write` method is now implemented on top of `write_message`,
+  always prefixing output with `command(<name>): `. The `who:` keyword
+  argument previously accepted by `write` has been removed; use
+  `write_message` instead.
+
+* **display pre-existing agent messages when the repl starts** <br>
+  When
+  [`LLM::Agent#repl`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
+  starts, any messages already in the agent's buffer are now rendered
+  in the REPL window. Previously the REPL started with an empty
+  transcript even when the agent carried prior conversation history,
+  making it harder to resume a session. Tool-call and tool-return
+  messages are skipped to avoid visual noise.
+
+### CLI
+
+* **add `bin/llm.rb` for launching the REPL from the command line** <br>
+  A new executable script (`bin/llm.rb`) provides a convenient way to start
+  an interactive REPL session directly from the terminal. It auto-detects
+  the provider from environment variables like `OPENAI_API_KEY`, supports
+  a `-p PROVIDER` flag for explicit provider selection, a `-t` flag for
+  temporary (non-persistent) sessions, and `-h` for help. Sessions are
+  automatically saved to `~/.llm.rb/` by default.
+
+### Fix
+
+* **agent: fix `path` restore on first run** <br>
+  Fix a bug where [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
+  called `@ctx.restore(path:)` even when the path's file did not exist.
+  The fix checks `File.readable?(@path)` before attempting to restore,
+  so the agent starts with a blank conversation on first use instead of
+  failing with a file-not-found error.
+
+* **tools: re-raise `LLM::Interrupt` to abort the turn** <br>
+  [`LLM::Tool::Git`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Git.html),
+  [`LLM::Tool::Mkdir`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Mkdir.html),
+  [`LLM::Tool::Rg`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Rg.html),
+  [`LLM::Tool::Ruby`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Ruby.html),
+  and
+  [`LLM::Tool::Shell`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Shell.html)
+  now re-raise `LLM::Interrupt` after killing their running command. The
+  previous behavior rescued the interrupt and killed the child process but
+  let the turn continue, which meant a cancelled tool call did not abort
+  the conversation turn. Re-raising ensures the entire turn is interrupted.
+
+* **tools: rescue `LLM::Interrupt` in shell-based tools** <br>
+  [`LLM::Tool::Shell`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Shell.html),
+  [`LLM::Tool::Git`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Git.html),
+  [`LLM::Tool::Mkdir`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Mkdir.html),
+  and
+  [`LLM::Tool::Rg`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Rg.html)
+  now rescue `LLM::Interrupt` and kill their running command, preventing
+  orphaned child processes when a tool is interrupted during execution.
+
+* **agent: fix default name derivation** <br>
+  Fix a bug where `LLM::Agent` used without a subclass derived its default
+  name as `"l-lm-agent"` instead of `"agent"`. The fix replaces the
+  regex-based parameterization with a pattern that correctly handles
+  single-word class names and multi-word namespaced names.
+
+* **function: `#params` always returns an `LLM::Object`** <br>
+  [`LLM::Function#params`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#params-instance_method)
+  now always returns an `LLM::Object` representing the function's parameter
+  schema. Previously it returned `nil` when a function defined no parameters,
+  forcing every caller to guard against `nil`. All provider adapters now use
+  `fn.params.to_h` instead of `fn.params || {type: "object", properties: {}}`.
+
+## v13.0.0
+
+v13.0.0 relicenses the project under the MIT license, replacing
+the Business Source License that was introduced in v12.0.0. No
+commercial license is needed. Commercial, personal, educational, and
+all other uses are now permitted under the standard MIT terms.
+
+Seven breaking changes. Concurrency strategies have been renamed
+(`:call` → `:sequential`, `:task` → `:async`), `spawn` is now
+`task`, and the `:async` strategy has been rebuilt from the ground
+up. It no longer blocks and now supports interruption. The compactor
+has been refactored into pluggable strategies. Interruption is now
+reliable across all six concurrency backends. The `functions` and
+`functions?` methods have been renamed to `pending_functions` and
+`pending_functions?`.
+
+### Migration from v12.6.0
+
+| Old | New |
+|-----|-----|
+| `fn.spawn(:call)` | `fn.task(:sequential)` |
+| `fn.spawn(:task)` | `fn.task(:async)` |
+| `ctx.wait(:call)` | `ctx.wait(:sequential)` |
+| `agent.concurrency :task` | `agent.concurrency :async` |
+| `LLM::Function::FiberGroup` | `LLM::Function::Fiber::Group` |
+| `LLM::Function::CallGroup` | `LLM::Function::Sequential::Group` |
+| `LLM::Function::TaskGroup` | `LLM::Function::Async::Group` |
+| `Compactor.new(model:, token_threshold:)` | `Compactor::Truncate.new(ctx)` |
+| `on_compaction(ctx, compactor)` | `on_compaction(compactor)` |
+| `ctx.functions` / `ctx.functions?` | `ctx.pending_functions` / `ctx.pending_functions?` |
+| `agent.functions` / `agent.functions?` | `agent.pending_functions` / `agent.pending_functions?` |
+
+### Breaking
+
+* **rename `LLM::Function#spawn` as `LLM::Function#task`** <br>
+  [`LLM::Function#task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#task-instance_method)
+  (previously `spawn`) now consistently returns a
+  [`LLM::Function::Task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Task.html)
+  object that can be spawned, waited on, and passed to
+  [`LLM::Function::Group`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Group.html).
+  The old implementation alternated between spawning immediately or
+  returning a raw thread or fiber.
+
+* **rename concurrency strategies (`:call` → `:sequential`,**
+  **`:task` → `:async`)** <br>
+  The `:call` concurrency strategy is now `:sequential`, and the `:task`
+  strategy is now `:async`.
+  [`LLM::Agent.concurrency`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#concurrency-class_method),
+  [`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait-instance_method),
+  `LLM::Function::Array#task`, and
+  [`LLM::Function#task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#task-instance_method)
+  all accept the new names. The old names raise `ArgumentError`.
+
+* **rename group classes** <br>
+  Group classes have been moved into their strategy's namespace:
+  `FiberGroup` → `Fiber::Group`, `ThreadGroup` → `Thread::Group`,
+  `CallGroup` → `Sequential::Group`, `TaskGroup` → `Async::Group`,
+  `Fork::Group` → `Fork::Group`, `Ractor::Group` → `Ractor::Group`.
+
+* **repurpose `LLM::Function::Task` as a task interface superclass** <br>
+  `LLM::Function::Task` has been repurposed from a general-purpose class
+  that tried to support multiple concurrency strategies into an abstract
+  base class that defines the task interface. Individual strategies
+  (`Sequential::Task`, `Thread::Task`, `Fiber::Task`, `Async::Task`,
+  `Fork::Task`, `Ractor::Task`) now subclass it and implement
+  `spawn`, `alive?`, `interrupt!`, and `wait`.
+
+* **fix `:async` concurrency (now backed by a managed**
+  **`LLM::Function::Async::Reactor` on a background thread)** <br>
+  The `:async` strategy previously used `Async {}` which blocked the
+  caller until all tasks completed and did not support interruption.
+  The fix replaces it with a per-turn
+  `LLM::Function::Async::Reactor` on a background thread. Work is
+  submitted via `submit(&block)` and consumed by the reactor's event
+  loop through a thread-safe `Queue`. `Async::Group` manages the
+  reactor lifecycle and spawns tasks lazily on `wait`.
+  <br><br>
+  Interruption pushes [`LLM::Interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Interrupt.html)
+  to the task's result queue instead of using `Fiber#raise`, and
+  results are bridged back to the caller through a second `Queue`.
+  This work drove the broader refactor of strategy naming, the
+  spawn/wait split, and the `Task` superclass. The `:async` strategy
+  needed the same interface the other strategies already had.
+
+* **compactor: refactor to strategy-based interface** <br>
+  [`LLM::Compactor`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor.html)
+  has been refactored from a single class that performed LLM-based
+  summarization into a strategy-based superclass. Each subclass
+  implements a different compaction strategy via `call(**opts)`. The old
+  summarization approach (using `model:`, `token_threshold:`,
+  `message_threshold:`, and `retention_window:` options) has been removed.
+  The built-in
+  [`LLM::Compactor::Truncate`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Truncate.html)
+  strategy drops the oldest messages when the conversation exceeds a
+  configured size.
+
+* **rename `LLM::Context#{functions,functions?}` and `LLM::Agent#{functions,functions?}`** <br>
+  [`LLM::Context#functions`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#functions-instance_method)
+  and
+  [`LLM::Context#functions?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#functions%3F-instance_method)
+  have been renamed to
+  [`LLM::Context#pending_functions`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions-instance_method)
+  and
+  [`LLM::Context#pending_functions?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#pending_functions%3F-instance_method)
+  respectively. The same rename applies to
+  [`LLM::Agent#functions`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#functions-instance_method)
+  (now
+  [`LLM::Agent#pending_functions`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#pending_functions-instance_method)).
+  The `pending_functions` name was already available as an alias in
+  v12.5.0; this change removes the old `functions` name entirely.
+
+### Core
+
+* **extend `LLM.require` with an optional version argument** <br>
+  `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", "~> 1.1"` 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.
+
+### Compactor
+
+* **add `Truncate` strategy for dropping oldest messages** <br>
+  [`LLM::Compactor::Truncate`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Truncate.html)
+  is a new built-in compaction strategy that drops the oldest messages
+  when the conversation exceeds a configured size. It preserves tool
+  call/return pairs so the algorithm never breaks in the middle of a
+  sequence. Configured with `keep:` (default 64), it emits the standard
+  `on_compaction` and `on_compaction_finish`
+  [`LLM::Stream`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html)
+  lifecycle callbacks. No LLM call is made; the strategy is purely
+  lossy but fast and requires no network.
+
+* **raise when given an unparseable `keep:` value** <br>
+  `LLM::Compactor::Truncate` now raises `ArgumentError` when the `keep:`
+  parameter cannot be parsed as an integer or percentage string, instead
+  of failing with an obscure error later during execution.
+
+* **accept percentage string for the `keep:` parameter** <br>
+  `LLM::Compactor::Truncate#call` now accepts a percentage string such
+  as `"80%"` for the `keep:` parameter, which keeps approximately 80%
+  of the most recent messages. Integer values continue to work as
+  before. This makes it easy to trim proportionally rather than to an
+  absolute number of messages.
+
+* **add `Null` strategy for no-op compaction** <br>
+  [`LLM::Compactor::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Null.html)
+  is a new built-in compaction strategy that does nothing. It is used as
+  the default compactor when no strategy is configured on a context,
+  ensuring the compactor interface is always present without requiring a
+  separate nil check.
+
+* **accept both `LLM::Agent` and `LLM::Context`** <br>
+  [`LLM::Compactor#initialize`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor.html#initialize-instance_method)
+  now accepts both `LLM::Agent` and `LLM::Context` instances. When given
+  an agent, the internal context is unwrapped automatically, making the
+  compactor API more flexible when working with agents.
+
+#### Context integration
+
+* **accept `compactor` and `compactor_options` parameters** <br>
+  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
+  now accepts `compactor:` (a compactor class defaulting to
+  [`LLM::Compactor::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Null.html))
+  and `compactor_options:` (a hash of options forwarded to the
+  compactor's `call` method) parameters. The compactor is automatically
+  invoked at the beginning of each `talk` turn. The previous `compactor=`
+  setter has been removed in favour of constructor-driven configuration.
+
+* **`on_compaction` and `on_compaction_finish` receive a single argument** <br>
+  [`LLM::Stream#on_compaction`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_compaction-instance_method)
+  and
+  [`LLM::Stream#on_compaction_finish`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_compaction_finish-instance_method)
+  now accept a single argument (the compactor instance) instead of two
+  arguments (context and compactor). The context is still available via
+  `LLM::Compactor#ctx`, so access to the context is not lost. This
+  simplifies the callback interface for compaction lifecycle observers.
+
+### Tools
+
+* **add `LLM::Tool::Utils` module for shared command execution logic** <br>
+  A new
+  [`LLM::Tool::Utils`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Utils.html)
+  module provides shared `wait(command:, timeout:)` and `now` helper
+  methods for tools that execute commands. Tools that include `Utils` can
+  wait on a running command and automatically kill it when it exceeds the
+  configured timeout, using `Process.clock_gettime` with `CLOCK_MONOTONIC`
+  for precise timing. The module is used by both the `Shell` and `Rg`
+  tools internally.
+
+* **shell: add `timeout` parameter for command execution deadlines** <br>
+  The
+  [`LLM::Tool::Shell`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Shell.html)
+  tool now accepts a `timeout` parameter (default 60s) that automatically
+  kills commands exceeding the specified time limit, preventing hung
+  processes from blocking the agent indefinitely.
+
+* **rg: add `timeout` parameter for search execution deadlines** <br>
+  The
+  [`LLM::Tool::Rg`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Rg.html)
+  tool now accepts a `timeout` parameter (default 5s) that automatically
+  kills search commands exceeding the specified time limit, preventing
+  long-running searches from blocking the agent indefinitely.
+
+* **git: add `timeout` parameter for command execution deadlines** <br>
+  The
+  [`LLM::Tool::Git`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Git.html)
+  tool now accepts a `timeout` parameter (default 5s) that automatically
+  kills git commands exceeding the specified time limit, preventing hung
+  processes from blocking the agent indefinitely.
+
+### Schema
+
+* **properties are now ordered and support indifferent access** <br>
+  [`LLM::Schema::Leaf`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema/Leaf.html)
+  tracks property definition order in a new `index` attribute, matching
+  the convention already used by
+  [`LLM::Command::Parameter`](https://r.uby.dev/api-docs/llm.rb/LLM/Command/Parameter.html).
+  Internally, `@properties` is stored as an
+  [`LLM::Object`](https://r.uby.dev/api-docs/llm.rb/LLM/Object.html)
+  instead of a plain `Hash`, so lookups with both string and symbol keys
+  work.
+
+### Buffer
+
+* **more array-like message management** <br>
+  [`LLM::Buffer`](https://r.uby.dev/api-docs/llm.rb/LLM/Buffer.html)
+  now exposes `first`, `reject!`, `select!`, `shift`, `clear`, `drop`,
+  `take`, and `reverse`, making it easier to query and mutate
+  `LLM::Context#messages` like an ordinary Array. `reject!` is aliased
+  as `delete_if` for familiarity.
+
+* **`last(nil)` no longer returns the last message** <br>
+  `LLM::Buffer#last` now uses an internal `UNDEFINED` sentinel to
+  distinguish between no argument (`last` returns the last message)
+  and `nil` (`last(nil)` is treated as an argument). Previously `nil`
+  was indistinguishable from no argument.
+
+### Function
+
+* **consolidate `call` and `call!` into one method** <br>
+  The private `call!` method has been merged into the public
+  [`LLM::Function#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#call-instance_method).
+  The separate `call!` method existed for tracer-scoping logic now
+  handled directly inside `call`. All internal call sites now use
+  `function.call` instead of `function.call!`.
+
+* **add `LLM::Function::Group` as an abstract base class** <br>
+  A new abstract base class
+  ([`LLM::Function::Group`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Group.html))
+  defines the interface that all concurrency strategy groups must
+  implement: `alive?`, `interrupt!`, and `wait`. Each strategy group
+  (`Sequential::Group`, `Thread::Group`, `Fiber::Group`,
+  `Async::Group`, `Fork::Group`, `Ractor::Group`) now subclasses
+  this base.
+
+* **split `spawn` and `wait` across all strategies** <br>
+  `spawn` now starts execution without blocking, and `wait` collects
+  the result. `on_tool_start` moved into each task's `spawn` so the
+  tracer span covers execution rather than construction. Each task and
+  group now exposes a public `spawn` method alongside the existing
+  `wait`/`value` methods.
+
+* **spawn tasks lazily in `Group#wait`** <br>
+  All concurrency strategy groups (Fiber::Group, Fork::Group,
+  Ractor::Group, Thread::Group) now automatically spawn their tasks
+  when `wait` is called if they haven't been spawned yet, matching
+  the existing `Async::Group` behavior. This makes the spawn/wait
+  contract consistent across all six concurrency backends.
+
+### Agent
+
+* **add `name` class DSL and instance method** <br>
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) now
+  has a `name` class DSL (`name "admin"`) and a corresponding `#name`
+  instance method. The name is resolved through the same lazy-resolution
+  path as other agent attributes. It can be set via
+  `LLM::Agent.set(name: ...)`, `LLM::Agent.new(name: ...)`, or the class
+  DSL. When no name is given, a default is derived from the class name
+  (e.g., `SystemAdmin` becomes `system-admin`). The REPL uses the name
+  as the prompt label and transcript prefix, making it easier to
+  distinguish multiple sessions.
+
+### REPL
+
+* **agent identity in the prompt** <br>
+  [`LLM::Agent#repl`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#repl-instance_method)
+  and
+  [`LLM::Repl.new`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl.html#initialize-instance_method)
+  accept a `name:` parameter (defaulting to `LLM::Agent#name`) that sets
+  the input prompt to `provider(name)> ` and labels transcript messages
+  with the agent's name instead of a hardcoded `agent:`. Useful when
+  running multiple sessions.
+
+* **`/compact` command** <br>
+  New built-in `/compact` command frees context window space by dropping
+  the oldest messages via
+  [`LLM::Compactor::Truncate`](https://r.uby.dev/api-docs/llm.rb/LLM/Compactor/Truncate.html).
+  Supports both integer (`/compact 32`) and percentage (`/compact 75%`)
+  arguments. Defaults to keeping the last 128 messages.
+
+* **tab-completion for `/` commands** <br>
+  Pressing Tab on an input line starting with `/` autocompletes the
+  command name. Repeated Tab presses cycle through matching commands.
+  Powered by
+  [`LLM::Command.complete(str)`](https://r.uby.dev/api-docs/llm.rb/LLM/Command.html#complete-class_method)
+  which is available outside the REPL too.
+
+* **command system enhancements** <br>
+  Commands can set parameter defaults in their `call` method signature
+  (e.g., `def call(n: 128)`). Aliases like `/quit` now inherit their
+  parent's description and parameters. Commands also have access to
+  the active `agent` and `repl` via public readers.
+
+* **tool argument sorting** <br>
+  Tool parameters in the status bar are now displayed in definition
+  order (using the new `index` attribute), regardless of the order
+  the model returns them.
+
+* **expanded markdown rendering** <br>
+  The curses-based markdown renderer now handles lists (`<ul>`, `<ol>`),
+  blockquotes, horizontal rules, hyperlinks (underline), images
+  (`[image: alt text]`), and tables (aligned columns).
+
+* **input improvements** <br>
+  Ctrl+P and Ctrl+N walk through conversation history (user messages
+  only, managed by
+  [`LLM::Repl::Walker`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Walker.html)).
+  Page Up/Down scroll the transcript by a page. ENTER and BACKSPACE are
+  now mapped to raw character codes from `Curses.getch` instead of
+  `Curses::Key` constants.
+
+### Object
+
+* **preserve the original key name in `KeyError` messages** <br>
+  `LLM::Object#fetch` now preserves the original key name when a key
+  is not found, instead of raising `KeyError` with `key not found: nil`.
+  The previous behavior occurred when the given key was not found in
+  the stored hash, causing internal lookup to return `nil` and lose
+  the original key reference.
+
+### Registry
+
+* **refresh model metadata across providers** <br>
+  Update `data/*.json` files with current provider model listings and
+  pricing. Mark several DeepInfra models as deprecated (`meta-llama/
+  Meta-Llama-3.1-8B-Instruct`, `Qwen/Qwen1.5-110B-Chat`, and
+  `mistralai/Mixtral-8x7B-Instruct-v0.1`). Correct xAI cache-read
+  pricing from $0.50 to $0.30 per million input tokens.
+
+### Fix
+
+* **agent: fix default name resolution when name is not explicitly set** <br>
+  Fix a bug where `LLM::Agent` derived its default name from
+  `self.class` instead of `self`, causing the name to be `"class"`
+  instead of a parameterized version of the actual class name
+  (e.g., `"system-admin"` for `SystemAdmin`). The fix uses `self`
+  directly, which correctly resolves the class name at the instance
+  level.
+
+* **function: make Fork::Task and Ractor::Task inherit LLM::Function::Task** <br>
+  `LLM::Function::Fork::Task` and `LLM::Function::Ractor::Task` now
+  explicitly subclass `LLM::Function::Task` and accept an options hash
+  as their second argument, matching the constructor signature used
+  by the other four task classes. The interface was already compatible
+  but the inheritance was missing by mistake. It is now consistent across
+  all six concurrency backends.
+
+* **google: fix `stream` parameter leakage that broke the provider** <br>
+  Fix a bug in the Google provider where `stream: stream.enabled?` was
+  being merged into request parameters, causing API-level errors. The
+  Google provider does not use a `stream` parameter. Streaming is
+  controlled via the URL path (`streamGenerateContent` vs
+  `generateContent`). The fix removes the leaked parameter and correctly
+  routes streaming requests through the appropriate path.
+
+* **fork: fix deadlock on xchan.rb channel** <br>
+  Fix a deadlock in the `:fork` concurrency strategy where both the
+  writer and reader could get stuck on the xchan channel, preventing the
+  reader from draining the channel. The deadlock surfaced as an errno
+  failure, especially with large tool returns. The fix requires xchan.rb
+  v0.22.0 and uses the `SOCK_STREAM` socket type for communicating a
+  tool's return value.
+
 ## v12.6.0
 
 Changes since `v12.5.1`.
 
-This release adds bulk defaults for tools and agents — `LLM::Tool.defaults`
+This release adds bulk defaults for tools and agents: `LLM::Tool.defaults`
 for setting parameter defaults and `LLM::Agent.set` for mass-assigning
 class-level defaults, both mirrored on ActiveRecord and Sequel agent models.
 
@@ -55,7 +613,7 @@ prior call.
   On cancel, `LLM::Interrupt` is now raised on the thread that is
   running a tool. The tool can rescue `LLM::Interrupt` and gracefully
   terminate (e.g., clean up resources). The previous approach used
-  `Thread#interrupt` which was less reliable — it did not interrupt a
+  `Thread#interrupt` which was less reliable. It did not interrupt a
   sleeping thread.
 
 * **function: suppress thread exception reporting in `:thread` concurrency** <br>
@@ -81,15 +639,15 @@ prior call.
   `LLM::Interrupt` is now raised on the active fiber via `Fiber#raise`
   when interrupting `:fiber`-concurrency tools.
   <br><br>
-  `Task#interrupt!` now dispatches by task type — `Thread#raise` for
-  threads, `Fiber#raise` for fibers — making interruption reliable
+  `Task#interrupt!` now dispatches by task type: `Thread#raise` for
+  threads, `Fiber#raise` for fibers. Making interruption reliable
   across all concurrency strategies.
 
 * **function: raise `LLM::Interrupt` on fork-backed tool tasks** <br>
   `LLM::Interrupt` is now raised on the main thread of a fork child
   process via `Thread.main.raise(LLM::Interrupt)` when interrupting
   `:fork`-concurrency tools, and the fork `Task#wait` re-raises the
-  interrupt on the parent side — making interruption reliable across
+  interrupt on the parent side. Making interruption reliable across
   all concurrency strategies including `:fork`.
 
 * **function: raise `LLM::Interrupt` on `Async::Task`-backed tool tasks** <br>
@@ -107,7 +665,7 @@ prior call.
   raises `LLM::Interrupt` on the ractor's main thread.
   <br><br>
   `Task#interrupt!` delegates to the mailbox to send the interrupt
-  message — extending reliable interruption to the `:ractor`
+  message. Extending reliable interruption to the `:ractor`
   concurrency strategy.
 
 ## v12.5.1
@@ -254,7 +812,7 @@ OpenAI, Google, DeepInfra, DeepSeek, and xAI model entries.
 
 * **repl: display command errors in the curses UI** <br>
   Commands invoked with too few arguments now display an error
-  message — `command(<name>): too few arguments` — directly in
+  message: `command(<name>): too few arguments`. Displayed directly in
   the curses transcript area, giving immediate feedback instead
   of silently failing.
 
@@ -378,7 +936,7 @@ a command system foundation with the `/exit` command, and several new
 keybindings (Ctrl+F, Ctrl+K, Ctrl+Y). Tool calls are rendered with a
 compact function-call syntax in the status bar.
 
-Two new built-in tools — `LLM::Tool::Ls` and `LLM::Tool::Which` — are
+Two new built-in tools: `LLM::Tool::Ls` and `LLM::Tool::Which` are
 available as opt-in additions for file listing and executable lookup.
 
 Model metadata has been refreshed across providers, the REPL loop
@@ -445,7 +1003,7 @@ area.
   The curses-based REPL input now detects paste operations by tracking
   the rate at which characters arrive. A paste rate of ≤50ms is
   assumed to be a burst of characters that could only be explained by
-  a paste — no human types that fast. Multiline pastes are supported
+  a paste. No human types that fast. Multiline pastes are supported
   through internal refactoring of the input handling logic.
 
 * **repl: optimize paste mode rendering** <br>
@@ -468,7 +1026,7 @@ area.
 
 * **repl: render tool calls in a function-call syntax** <br>
   The curses-based REPL status bar now renders tool calls with a
-  compact function-call syntax — `tool(key: value)` instead of
+  compact function-call syntax: `tool(key: value)` instead of
   `tool: name`. Strings are quoted and truncated, arrays show their
   first two elements, and hashes collapse to `{…}`, making it easier
   to see what arguments the model is passing. The `tool done` status
@@ -596,8 +1154,8 @@ tracer logger instances with less verbosity.
   streamed content via `#<<`. `LLM::Stream::Disabled` represents an explicitly
   disabled stream with no-op callbacks.
 
-  This is part of an internal refactoring that lets all stream values — IO
-  objects, `true`, `false`, `nil`, and `LLM::Stream` instances themselves —
+  This is part of an internal refactoring that lets all stream values: IO
+  objects, `true`, `false`, `nil`, and `LLM::Stream` instances themselves
   be represented by the same `LLM::Stream` interface via the new
   `LLM::Stream.try` factory method.
 
@@ -666,7 +1224,7 @@ tracer logger instances with less verbosity.
 
 * **repl: add extra padding between markdown nodes** <br>
   The curses-based REPL markdown renderer now adds extra vertical spacing
-  between certain markdown elements — paragraphs, headers, and codeblocks —
+  between certain markdown elements: paragraphs, headers, and codeblocks
   for improved readability of model responses.
 
 * **repl: add a visual divider between transcript and the rows below it** <br>