llm.rb 13.0.0 → 14.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0304f2a840c94209256729edf114209ffab0bdd309d1a25172818458e4c3f4f
-  data.tar.gz: 46c695d1722ef6e618f27eb9b433f77774bf9140bfd31983589946be3ce53c1e
+  metadata.gz: 80d9ecf944df7561e9a0ac70bb37225dac11f18b13fba94d689b672da3b27e6f
+  data.tar.gz: d3986e29989bcd415c40cd26fd4361ac8b3f92461cf81f2f5abf5a9d291cd068
 SHA512:
-  metadata.gz: 0a9da53406a6e612f68412005d33b0e85bf6064c9c38ff70e5cd2290f8b381bbba9ae9becd6ca71b15fed399e1d84bdd55972301d0cdb51c10d528d00f5a5d8f
-  data.tar.gz: 882a041334ad21b83397792e3921510c0298b0c623b6c05441117f5655ac1fbe35b560cb015b29bcbd0aad526cc772d9e58596567c72d456d3ee77adc372f397
+  metadata.gz: 702cd38c23fa817b068dd9b7c8942f3641915c874e1ed9bef6526127767092f138fd09c320cd54fafc265e2b33131d0cca8b7376f2c7b5e9e3203e66b1f4a513
+  data.tar.gz: f5eebb31abe9349e451bb1410b01a35353dd466fc66b6df230c5cb6be469856be234dea3351f885eb9c616375c0b84bf18e72dc268b88454997919f475a89774

data/CHANGELOG.md

@@ -15,7 +15,498 @@
 
 ## What's next
 
-_No unreleased changes yet._
+*No unreleased changes yet. Check back after the next release.*
+
+## v14.0.0
+
+Changes since `v13.1.0`.
+
+This release replaces the `transformer=` setter with the new
+`LLM::Transformer` class hierarchy, refactors guards into the
+`LLM::Guard` superclass with per-tool-call interception, and replaces
+the agent `tool_attempts` parameter with the `tool_budget` class DSL.
+It also adds the Moonshot (Kimi) provider, the `LLM::Tool.set`
+bulk-assignment DSL, a `LLM::Function#return` shorthand, and a wide
+range of REPL improvements.
+
+### Breaking
+
+#### Migration
+
+| Old | New |
+|-----|-----|
+| `ctx.transformer = MyTransformer` | `LLM::Context.new(transformer: MyTransformer)` |
+| `transformer.call(ctx, prompt, params)` | `transformer.call(message:, **opts)` |
+| `~/.llm.rb/session.json` (shared across providers) | `~/.llm.rb/<provider>/<uuid>.json` (scoped per provider and directory) |
+| `agent.talk(tool_attempts: 25)` | `set :tool_budget => 50` (disabled by default) |
+| `LLM::LoopGuard` | `LLM::Guard::Loop` |
+| `guard: true` / `ctx.guard = MyGuard` | `guard: MyGuard, guard_options: {}` |
+| `guard.call(ctx)` (warning string) | `guard.call(function:)` (`LLM::Function::Return` or nil) |
+| `LLM::GuardError` | `"guard_error"` |
+
+* **replace the transformer setter with `LLM::Transformer`** <br>
+  The previous `transformer=` setter and 3-argument
+  `call(ctx, prompt, params)` interface on `LLM::Context` have been
+  replaced by the new
+  [`LLM::Transformer`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer.html)
+  class interface. Configure a transformer class through `transformer:`
+  and options through `transformer_options:` instead.
+
+* **cli: scope session persistence per provider and directory** <br>
+  `bin/llm.rb` no longer shares a single session file between providers.
+  Each provider now has a `~/.llm.rb/<provider>.json` file that maps the
+  current working directory to a UUID-scoped session file under
+  `~/.llm.rb/<provider>/<uuid>.json`, so sessions are scoped to both the
+  provider and the directory they were started in.
+
+* **cli: harden the executable against bad inputs** <br>
+  `bin/llm.rb` now prints an error message followed by the help menu and
+  exits with status 1 when the `-p` switch is given without an argument or
+  when an unknown option is passed. Previously unknown options produced a
+  warning but the run continued. The session-file lookup also no longer
+  rewrites `~/.llm.rb/<provider>.json` when it already exists.
+
+* **agent: replace `tool_attempts` with the `tool_budget` class DSL** <br>
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
+  replaces the `tool_attempts` parameter with a `tool_budget` class DSL
+  (`tool_budget { 50 }`) that caps the number of tool calls allowed in a
+  single turn. Once the budget is spent, the agent sends an in-band
+  advisory message back through the model telling it to solve the problem
+  with fewer tool calls.
+  <br><br>
+  The feature is now disabled by default; the old `tool_attempts`
+  parameter defaulted to 25, which long-horizon agents could easily
+  exhaust in a single turn.
+
+* **guard: replace `LLM::LoopGuard` with the `LLM::Guard` class hierarchy** <br>
+  [`LLM::Guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html)
+  is a new superclass for context-level supervisors, with
+  [`LLM::Guard::Loop`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Loop.html)
+  (replacing `LLM::LoopGuard`) and
+  [`LLM::Guard::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard/Null.html)
+  as the built-in implementations.
+  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
+  now accepts `guard:` (a guard class defaulting to `LLM::Guard::Null`)
+  and `guard_options:` (a hash forwarded to the guard's `call` method),
+  matching the transformer and compactor interfaces. The old boolean and
+  hash forms of `guard` and the `guard=` setter are removed. `LLM::Agent`
+  enables `LLM::Guard::Loop` by default.
+
+* **guard: block individual tool calls instead of the whole batch** <br>
+  [`LLM::Guard#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html#call-instance_method)
+  now receives the pending `function:` and returns an
+  [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+  (or nil) instead of a warning string for the entire batch, so a guard
+  can block a single tool call while the rest of the batch still
+  executes. Custom guards that implemented the old `call(ctx)`
+  warning-string interface must be updated to return a
+  `LLM::Function::Return` instead.
+
+* **errors: drop `LLM::GuardError`** <br>
+  Remove `LLM::GuardError`. The constant was never raised as an
+  exception; it only named the in-band error type for guarded tool
+  returns. Guarded tool returns now use the string `"guard_error"` as
+  their error type.
+
+### Core
+
+* **add `LLM::Provider#build_messages` for assembling outgoing messages** <br>
+  [`LLM::Provider#build_messages`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#build_messages-instance_method)
+  normalizes a prompt into `LLM::Message` objects and prepends the existing
+  history, replacing the per-provider `build_complete_messages`
+  implementation. The method is idempotent: prompts that are already
+  [`LLM::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html)
+  instances or arrays of messages are returned as-is.
+
+* **copy the `params` hash in `LLM::Context` and `LLM::Agent`** <br>
+  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html) and
+  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) now copy
+  the `params` hash in their constructors before mutating it, leaving the
+  caller's hash untouched. Previously the constructors deleted keys from
+  the caller's hash in place.
+
+* **gemspec: ship the deepdive sub-files in the gem** <br>
+  The gemspec now includes `resources/deepdive/*/*.md` in the gem
+  package, so the full deepdive guide (fundamentals, advanced,
+  protocols, and everything-else chapters) is available after
+  installation.
+
+* **add short aliases to `LLM::Cost`** <br>
+  [`LLM::Cost`](https://r.uby.dev/api-docs/llm.rb/LLM/Cost.html) now
+  offers short aliases for its cost accessors: `input`, `output`,
+  `input_audio`, `output_audio`, `input_image`, `cache_read`,
+  `cache_write`, and `reasoning`. Each alias matches the key used by
+  `#to_h`, so `cost.input` reads the same value as `cost.input_costs`.
+
+### Provider
+
+* **add `LLM::Moonshot` for the Moonshot AI provider** <br>
+  [`LLM::Moonshot`](https://r.uby.dev/api-docs/llm.rb/LLM/Moonshot.html)
+  is a new provider that talks to
+  [Moonshot AI](https://platform.moonshot.ai) through its
+  OpenAI-compatible Kimi API. Create an instance with
+  [`LLM.moonshot`](https://r.uby.dev/api-docs/llm.rb/LLM.html#moonshot-class_method),
+  which accepts the same `key:`, `host:`, and `base_path:` options as the
+  OpenAI provider. The provider defaults to the `kimi-k3` model and
+  supports chat completions, streaming, tool calls, and structured output
+  through the shared OpenAI-compatible path; image, audio, moderation,
+  responses, and vector store endpoints raise `NotImplementedError`.
+  Model metadata ships in `data/moonshot.json` for the registry.
+
+### Transformer
+
+* **add `LLM::Transformer` for rewriting messages before they reach the provider** <br>
+  [`LLM::Transformer`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer.html)
+  is a new superclass for message transformers. A transformer is bound to a
+  context and rewrites a single message before it is sent to the provider,
+  which makes it possible to redact personal information or rewrite any
+  message before it goes out over the wire. Each subclass implements
+  `call(message:, **opts)` and returns the message to send, either by
+  mutating it in place or returning a new one.
+  [`LLM::Transformer::Null`](https://r.uby.dev/api-docs/llm.rb/LLM/Transformer/Null.html)
+  is a no-op transformer used as the default.
+
+* **hook the transformer API into `LLM::Context`** <br>
+  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html) now
+  accepts `transformer:` (a transformer class defaulting to
+  `LLM::Transformer::Null`) and `transformer_options:` (a hash forwarded to
+  the transformer's `call` method). The transformer runs on the most recent
+  message in both chat and responses turns.
+  [`LLM::Stream#on_transform`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_transform-instance_method)
+  and
+  [`LLM::Stream#on_transform_finish`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_transform_finish-instance_method)
+  now receive the transformer instance as their single argument.
+
+### Tool
+
+* **add `LLM::Tool.set` for bulk-assigning tool properties** <br>
+  [`LLM::Tool.set`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#set-class_method)
+  accepts a hash of `name`, `description`, `parameters`, `required`, and
+  `defaults` to configure a tool subclass in a single call. Parameters are
+  defined as tuples of `[name, type, description, options]`, matching the
+  same interface as the existing `parameter` DSL. Unknown keys raise
+  `KeyError`.
+
+### Function
+
+* **add `LLM::Function#return` for building tool returns** <br>
+  [`LLM::Function#return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#return-instance_method)
+  returns an
+  [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
+  built from the function's own id and name, using the given hash as its
+  value. It is a shorthand mainly useful inside a
+  [`LLM::Guard`](https://r.uby.dev/api-docs/llm.rb/LLM/Guard.html)
+  subclass and is defined via `define_method` because `return` is a Ruby
+  keyword.
+
+### Guard
+
+* **run the guard for streamed tool calls** <br>
+  Fix a gap where the guard was not consulted when a tool call was queued
+  while a response was still streaming. The guard is now stamped onto the
+  functions a context binds, so it runs wherever a task is spawned,
+  including tool calls queued from a stream. A blocked call yields its
+  `guard_error` return without executing.
+
+### Agent
+
+* **add `LLM::Agent#compacted?`** <br>
+  [`LLM::Agent#compacted?`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#compacted%3F-instance_method)
+  delegates to the wrapped
+  [`LLM::Context#compacted?`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#compacted%3F-instance_method)
+  and reports whether the conversation has been compacted, so callers
+  can detect when history was trimmed.
+
+### Change
+
+* **openai: default to `gpt-5.6-luna`** <br>
+  The default OpenAI chat model has changed from `gpt-5.4-mini` to
+  `gpt-5.6-luna`. The new model is OpenAI's fastest and most affordable
+  option, matching the kind of default llm.rb aims for.
+
+### Repl
+
+* **show an unknown context state after `/compact`** <br>
+  After running `/compact`, the REPL status line now renders `Context
+  compacted` and the context-usage bar shows `???` instead of a percentage,
+  because the used context is unknown until the next response.
+
+* **land on a blank line after Ctrl+N at the end of history** <br>
+  When recalling history with Ctrl+P and Ctrl+N, Ctrl+N at the last item
+  now advances to a blank line so you can start typing new input, instead
+  of staying stuck on the last item in history (the previous behavior).
+  Recalling with Ctrl+P or Ctrl+N also no longer overwrites the input when
+  there is no history to show.
+
+* **restore history wrap for Ctrl+P and Ctrl+N** <br>
+  Fix a regression where Ctrl+P and Ctrl+N recalled history text without
+  reflowing it into rows, so recalled lines wider than the terminal were
+  clipped. Recalled text now flows through the same word-wrap path as
+  typed input and wraps at the terminal width.
+
+* **restore Ctrl+D deletion across rows** <br>
+  Fix a bug where Ctrl+D at the end of an input row was a no-op, so
+  multiline input could not be joined by deleting a row break. Deleting
+  at the end of a row now consumes the break and pulls the next row up,
+  restoring the split space so merged words do not run together.
+
+* **center the buffer with 20% gutters** <br>
+  The curses-based REPL now centers
+  [`LLM::Repl::Buffer`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Buffer.html)
+  in a content area that is 60% of the terminal width, with an unused 20%
+  gutter on each side. The drawing area is based on the available rows and
+  columns instead of a fixed 80-column width, and `Buffer#wrap` now
+  hard-breaks words that overflow the width onto the next row, fixing a
+  bug where a word could be cut off between rows.
+
+* **apply markdown to previous messages** <br>
+  The curses-based REPL now renders every message in the buffer with
+  markdown styling, including messages that were already present when
+  the session started or restored from disk. Previously only newly
+  streamed responses were styled; older messages fell back to plain
+  text.
+
+* **add `LLM::Repl#sender` for the user label** <br>
+  [`LLM::Repl#sender`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl.html#sender-instance_method)
+  returns the label used for user messages in the curses-based REPL. It
+  defaults to `"You"` (previously `"user"`), and the buffer layout now
+  places each label on its own line followed by the message content and a
+  blank line.
+
+* **add `LLM::Repl::Color` for coloring the curses UI** <br>
+  Add
+  [`LLM::Repl::Color`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Color.html)
+  as a new module that returns Curses color bitmasks. `Color.enable`
+  initializes 8 color pairs, and methods like `Color.blue` return the
+  corresponding `Curses.color_pair(X)` bitmask, which can be bitwise
+  OR'ed with other attributes such as `Curses::A_BOLD`. User labels in
+  the REPL are now rendered in blue instead of plain bold text.
+
+* **split on words rather than characters** <br>
+  `LLM::Repl::Buffer#wrap` now breaks text on word boundaries instead of
+  wrapping one character at a time. A word that does not fit on the
+  current row moves to the next, and only a single word longer than the
+  whole width is hard-broken, so text is never clipped by the window.
+
+* **render kramdown typographic symbols and smart quotes** <br>
+  Fix a bug where certain character sequences such as `...` were not
+  rendered at all in the curses-based REPL. Kramdown parses them into
+  `:typographic_sym` and `:smart_quote` nodes, which previously fell
+  through to the children clause and were dropped. The markdown renderer
+  now maps them to their unicode equivalents: ellipsis, en and em
+  dashes, guillemets, and single and double quotation marks.
+
+* **apply colors to the markdown renderer** <br>
+  The curses-based REPL now renders markdown with the `LLM::Repl::Color`
+  palette: headers and strong text in white, code spans and code blocks
+  in green, and links in underlined green, on the black background.
+  Previously markdown styling used bold, underline, and reverse video
+  attributes only.
+
+* **wrap the input line at word boundaries** <br>
+  The curses-based REPL input line now wraps words whole onto the next
+  row at the terminal width instead of cutting them in half. A word that
+  does not fit on the current row moves to the next row, and only a
+  single word longer than the whole width is hard-broken, so typed text
+  is never clipped by the window.
+
+* **distinguish the connecting and thinking status bar phases** <br>
+  The curses-based REPL status bar now shows `Connecting • Esc to
+  cancel` while the model is establishing a connection, then switches
+  to `Thinking • Esc to cancel` once a tool call or text fragment
+  arrives on the stream. Active tool calls appear in the status bar
+  with a lambda indicator.
+
+* **add emoji to the status bar phases** <br>
+  The curses-based REPL status bar now uses emoji to identify each
+  phase at a glance: a globe (`🌐`) while the model is connecting, and
+  a brain (`🧠`) while it is thinking. The text after the emoji still
+  reads `Connecting • Esc to cancel` and `Thinking • Esc to cancel`
+  respectively.
+
+* **render the status bar with color and attributes** <br>
+  The curses-based REPL status bar now supports colored and attributed
+  status text, so the lambda indicator for active tool calls is drawn
+  in bold red.
+
+### Registry
+
+* **refresh model metadata across providers** <br>
+  Update `data/*.json` files with current provider model listings and
+  pricing. Remove the deprecated Claude Opus 4.1 entries from the
+  Anthropic registry, add `Qwen/Qwen3.8-Max` to DeepInfra, and add a
+  `low` reasoning-effort option to DeepSeek.
+
+## 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
 
@@ -406,7 +897,7 @@ reliable across all six concurrency backends. The `functions` and
 
 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.
 
@@ -442,7 +933,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>
@@ -468,15 +959,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>
@@ -494,7 +985,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
@@ -641,7 +1132,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.
 
@@ -765,7 +1256,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
@@ -832,7 +1323,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>
@@ -855,7 +1346,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
@@ -983,8 +1474,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.
 
@@ -1053,7 +1544,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>