llm.rb 12.3.1 → 12.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1be1cd2af0cc8a817e510b04d1d74efd08cedf714b3faff4bdb7a58345fe14f
-  data.tar.gz: 3768fdf7f131d30c04d0ba83514bec31eb8d64de661980aa811a4e804a4df1e5
+  metadata.gz: 665281b1c81541ff2f9621138cee510e473dfbda2c7dcff7d1a324e5fe558c89
+  data.tar.gz: c3ee596e41885038dc831ef6459da330d1984fea0125a9dbc5aa7d0ff8e21061
 SHA512:
-  metadata.gz: 667c546559bb199c7381fbea97171b5e82e874098c40a763004db85667038aa430fa98592c4d42b1426e4536e288e70c018278b9e7af9fcf9b6d972eabd65cbe
-  data.tar.gz: 0163f85848ce7292905396458755d9ccb23298c6f7c6f06cf0532fb3bdb3517e1b188a022937eb540b823d82d7bc8d869549bc17c8d79767c5efe027bf5ae9be
+  metadata.gz: cecf7fa0a2b1c6aff010c537b6741c74e537104eb9a67e3c2cd2840d06963040834c87263f71f6a1f815a4be831efa7740b2c03eb3f5fde9bbb274be4ee69c5c
+  data.tar.gz: 8b695e7c1656bf427bb095a257e954437b5b2dfc46e4d22349eb91dab9981eac1c5fc6b46bca89ecfec14986d386a0fba6303ef4dcf39a82345d3a136e944092

data/CHANGELOG.md

@@ -15,8 +15,403 @@
 
 ## What's next
 
+Changes since `v12.5.0`.
+
+## v12.5.0
+
+Changes since `v12.4.0`.
+
+This release extends the REPL command system with typed parameters, a
+built-in `/help` command, command aliases (`/quit`), and cancellation
+via the 'Esc' key.
+
+The default HTTP timeout is increased to 15 minutes (900s) to better
+accommodate reasoning models and large structured outputs.
+`LLM::Agent#deserialize` and `LLM::Agent#restore` now return `self` for
+method chaining, and `LLM::Buffer#pop` is added for tail-end message
+removal.
+
+Tool resolution gains a fallback to the global `LLM::Function` registry
+before raising `LLM::NoSuchToolError`, and `pending_functions` aliases
+are added on both contexts and agents for a consistent interface.
+
+Several REPL bugs are fixed including parameter state leakage across
+turns and invalid tool-call error routing.
+
+Model metadata is refreshed across all providers with new Anthropic,
+OpenAI, Google, DeepInfra, DeepSeek, and xAI model entries.
+
+### Add
+
+#### Buffer & function internals
+
+* **buffer: add `LLM::Buffer#pop`** <br>
+  Add `LLM::Buffer#pop` for removing the last message from the tail
+  of the buffer, complementing the existing `#<<` and array-style
+  message management.
+
+* **function: add registry fallback for tool resolution** <br>
+  When resolving tool calls from a message, if the tool is not found
+  in the available tools list, it now also looks up the global
+  `LLM::Function` registry via `LLM::Function.find_by_name` before
+  creating a placeholder function. This improves tool resolution for
+  tools that are registered globally but not passed directly through
+  the request tool set.
+
+#### Consistent `pending_functions` aliases
+
+* **context: alias `LLM::Context#functions` as `LLM::Context#pending_functions`** <br>
+  Add `LLM::Context#pending_functions` as an alias for `LLM::Context#functions`,
+  so callers that prefer the more descriptive `pending_functions` name can use
+  it instead of `functions` when checking for unresolved tool work.
+
+* **agent: alias `LLM::Agent#functions` as `LLM::Agent#pending_functions`** <br>
+  Add `LLM::Agent#pending_functions` as an alias for `LLM::Agent#functions`,
+  matching the same alias on `LLM::Context`, so callers have a consistent
+  `pending_functions` interface across both contexts and agents.
+
+#### REPL command system
+
+* **repl: extend command system with parameter support** <br>
+  Commands can now declare typed parameters using the `parameter`
+  DSL, modelled after `LLM::Tool` and `LLM::Schema` conventions.
+  Parameters can be marked as required with `required %i[...]`,
+  and values are type-checked before being passed to `call`.
+  Argument parsing is handled by the repl: arguments are split
+  from the input string and assigned to parameters by position.
+
+  ```ruby
+  class Greeter < LLM::Command
+    name "greet"
+    description "Greets the given name"
+    parameter :name, String, "The person's name"
+    required %i[name]
+
+    def call(name:)
+      write("Welcome #{name}!\n")
+    end
+  end
+  ```
+
+* **repl: add `help` command** <br>
+  Add `LLM::Repl::Help` as a new built-in command, registered
+  automatically via the command registry. Typing `/help` shows
+  the `help` command's own name, description, and parameters,
+  while `/help <name>` shows details for a specific command,
+  including its parameters and whether each is required or
+  optional. Unknown command names produce an error message.
+
+  ```ruby
+  class Help < Command
+    name "help"
+    description "show help for a given command"
+    parameter :name, String, "The name of a command"
+
+    def call(name: nil)
+      if name.nil?
+        write("\n#{self.class.help}\n\n")
+      elsif command = LLM::Command.find_by(name:)
+        write("\n#{command.help}\n\n")
+      else
+        write "\nNo help for #{name} was found" \
+              "\nThat command doesn't exist.\n\n"
+      end
+    end
+  end
+  ```
+
+* **repl: add support for command aliases** <br>
+  Commands can now be aliased by creating a subclass of another
+  command (with `LLM::Command` as an indirect ancestor). The
+  first alias introduced is `/quit` as an alias of `/exit`.
+
+  ```ruby
+  class Quit < Command::Exit
+    name "quit"
+  end
+  ```
+
+* **repl: add `Command::Parameter#optional?`** <br>
+  Parameters now expose an `#optional?` method that returns `true`
+  when a parameter has not been marked as required, making it
+  possible to query parameter optionality programmatically.
+
+* **repl: add `LLM::Repl::Command#write`** <br>
+  Commands can now write output to the transcript via the `write`
+  method. Commands also receive a reference to the active repl
+  through their `#initialize` method, making it possible to
+  interact with the repl window from within a command.
+
+* **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
+  the curses transcript area, giving immediate feedback instead
+  of silently failing.
+
+* **repl: add `LLM::Command` convenience constant** <br>
+  Add `LLM::Command = LLM::Repl::Command` as a shorter alias,
+  available once `"llm/repl"` is required.
+
+#### Misc
+
+* **repl: implement cancellation with the 'Esc' key** <br>
+  The curses-based REPL now supports cancelling an active model
+  request by pressing the 'Esc' key. When a request is in progress,
+  the status line shows `thinking • Esc to cancel`, and pressing
+  Esc calls `LLM::Agent#cancel!` to interrupt the request. The
+  transcript displays `request cancelled!` to confirm the
+  cancellation.
+
+### Change
+
+#### Misc
+
+* **provider: increase default timeout to 900s** <br>
+  The default HTTP timeout for all providers has been increased from
+  180 to 900 seconds (15 minutes) to better accommodate long-running
+  requests such as reasoning models and large structured outputs.
+
+* **agent: `deserialize` and `restore` return `self`** <br>
+  `LLM::Agent#deserialize` and `LLM::Agent#restore` now return `self`
+  (the agent instance) instead of forwarding the context's return
+  value, enabling method chaining after restoring agent state.
+
+* **context: discard all messages from a cancelled turn** <br>
+  When `LLM::Context#cancel!` is called, all messages added during
+  that turn are now discarded via `Buffer#slice!`, preventing edge
+  cases where dangling tool calls between turns caused repeated
+  cancellation loops. The `#repair!` method now handles tool call
+  cancellations on the next turn instead of mutating the conversation
+  buffer directly at cancellation time.
+
+* **stream: drop the `error` argument from `on_tool_call`** <br>
+  The `on_tool_call` callback no longer accepts an `error` argument.
+  Previously, stream parsers passed both a tool and an optional error,
+  requiring boilerplate like `if error; queue << error; end` in every
+  callback. Error handling is now pushed directly onto the stream queue
+  inside each provider's stream parser, so `on_tool_call(tool)` is the
+  only signature. The REPL stream and base `LLM::Stream` class have
+  been updated accordingly.
+
+#### REPL internals
+
+* **repl: pass the repl instance to command constructors** <br>
+  `LLM::Repl::Command` subclasses now receive the active repl
+  instance via `initialize(repl)`, enabling commands to write
+  to the transcript and interact with the repl window.
+
+* **repl: `Command#write` prefixes messages with the command name** <br>
+  The `#write` method now prefixes output with `command(<name>): `
+  so command messages are consistent with the `user:` and `agent:`
+  labels in the transcript. The prefix can be customised with the
+  `who:` keyword argument, or set to `who: nil` to disable it
+  entirely.
+
+### Fix
+
+#### Misc
+
+* **function: avoid silent skip of tools not found in available tools** <br>
+  When a model calls a tool that is not present in the available tools
+  list, instead of silently skipping the tool call (via `next`), a
+  `LLM::NoSuchToolError` is now raised so the model receives feedback
+  about the invalid tool call and can correct course.
+  <br><br>
+  An additional fallback to the global `LLM::Function` registry is
+  tried before raising, so globally registered tools are still
+  resolved even when not in the per-request tool set.
+
+#### REPL bugs
+
+* **repl: don't persist parameter state between turns** <br>
+  Parameter state (such as `Parameter#value`) was leaking across
+  turns because the same parameter objects were being mutated
+  in place. A duplicate set of parameters is now created for each
+  turn, keeping the original parameter definitions intact and
+  preventing stale state from carrying over.
+
+* **repl: reply with error when given an invalid tool** <br>
+  When the model tries to call a tool that does not exist, the
+  error is now pushed onto the stream queue so the model can
+  see the error and correct course, instead of silently dropping
+  the invalid tool call and leaving it to `Context#repair` to
+  remove it from history.
+
+* **repl: fix save of initial runtime state** <br>
+  Fix a bug in `LLM::Repl#configure` where a non-existent path
+  argument was treated as no path at all, preventing the initial
+  runtime state from being saved after the first turn. The correct
+  behavior is to create the file so it can be written to after
+  the first turn completes.
+
+### Refresh
+
+* **Refresh model metadata across all providers** <br>
+  Update model listings, pricing, capabilities, reasoning options,
+  modality support, context limits, and release dates across all
+  provider registries (Anthropic, AWS Bedrock, DeepInfra, DeepSeek,
+  Google, Mistral, OpenAI, xAI, and ZAI). Notable changes include
+  Anthropic claude-opus-4-8 and claude-sonnet-4-6 additions with
+  effort-based reasoning, OpenAI gpt-5.6-sol/terra/luna and
+  gpt-5-codex additions, Google gemini-3-pro-preview and
+  gemini-3-flash-preview additions, DeepInfra Qwen3.5 and DeepSeek
+  V4 model additions, and updated xAI Grok model entries.
+
+## v12.4.0
+
 Changes since `v12.3.1`.
 
+This release brings major improvements to the curses-based REPL
+(`LLM::Agent#repl`). The REPL now supports saving and restoring runtime
+state across sessions, automatic paste-mode detection for fast bulk input,
+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
+available as opt-in additions for file listing and executable lookup.
+
+Model metadata has been refreshed across providers, the REPL loop
+internals have been refactored to use `catch`/`throw` for cleaner command
+routing, and several bugs have been fixed including a tracer restoration
+issue in the agent ensure clause and a missing cursor in the REPL input
+area.
+
+### Add
+
+* **repl: allow runtime state to be saved and restored** <br>
+  `LLM::Agent#repl` now accepts a `path:` option that serializes
+  runtime state to the filesystem. When the path already exists,
+  runtime state is restored when the read-eval-print loop starts.
+  Otherwise the path is written after the first turn, making it
+  possible to resume a session across process restarts.
+
+* **repl: scroll to the bottom on submit** <br>
+  The curses-based REPL now scrolls the transcript to the bottom when
+  the user submits their input, so the latest response is visible
+  without needing to scroll down manually.
+
+* **repl: add Ctrl+F to move the cursor forward** <br>
+  The curses-based REPL input now supports Ctrl+F to move the cursor
+  forward by one column, matching common terminal editing conventions
+  found in shells like `/bin/sh`.
+
+* **repl: add Ctrl+K to erase from cursor to end of line** <br>
+  The curses-based REPL input now supports Ctrl+K to erase all text
+  from the cursor position to the end of the input buffer, matching
+  common terminal editing conventions found in shells like `/bin/sh`.
+
+* **repl: add Ctrl+Y to paste previously killed text** <br>
+  The curses-based REPL input now supports Ctrl+Y to insert the most
+  recently killed text (via Ctrl+K) at the current cursor position,
+  matching the yank/paste convention found in shells like `/bin/sh`.
+  The killed text is stored in an internal copy buffer so it can be
+  pasted multiple times or at different cursor positions.
+
+* **repl: add command system foundation** <br>
+  Add `LLM::Repl::Command` as a new base class for REPL commands,
+  along with the first built-in command `LLM::Repl::Command::Exit`
+  which exits the read-eval-print loop via `throw(:exit)`.
+  Commands are identified by a name and can be looked up through
+  `Command.find_by`. This is the foundation for the `/` command
+  syntax used in the REPL input line.
+
+* **repl: connect the command system to user input** <br>
+  The curses-based REPL now routes user input through the command
+  system. Any input string beginning with `"/"` is matched against
+  the command registry via `Command.find_by`, and the corresponding
+  command is executed instead of being forwarded to the model.
+  This makes built-in commands like `/exit` functional from the
+  input line. Command arguments are not yet supported.
+
+* **repl: add `LLM::Repl::Command.registry`** <br>
+  Add `LLM::Repl::Command.registry` for auto-registering command
+  subclasses. The `inherited` hook captures each new subclass and
+  stores it in the registry, making it possible to enumerate all
+  available commands at runtime. Built-in commands like Exit are
+  automatically registered when the command file is loaded.
+
+* **repl: detect and handle paste mode in the input line** <br>
+  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
+  through internal refactoring of the input handling logic.
+
+* **repl: optimize paste mode rendering** <br>
+  Track the paste state with an internal `@paste` variable and switch
+  to a faster input path during paste operations. While in paste mode,
+  the input buffer is drained via `Curses.getch`, bypassing the more
+  expensive char-by-char render path used for ordinary interactive
+  input. This makes pasting large amounts of text noticeably faster.
+
+* **Add `LLM::Tool::Ls`** <br>
+  Add a built-in tool for listing files and directories, with optional
+  glob pattern filtering to narrow results. <br>
+  It must be required explicitly with `require "llm/tools/ls"`.
+
+* **Add `LLM::Tool::Which`** <br>
+  Add a built-in tool for locating an executable on the system PATH.
+  This lets an agent check whether a command is available before
+  attempting to run it, avoiding failed subprocess calls. <br>
+  It must be required explicitly with `require "llm/tools/which"`.
+
+* **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
+  `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
+  message has been removed since the tool call itself conveys
+  completion information.
+
+### Change
+
+* **Refresh model metadata** <br>
+  Update model listings, pricing, and capabilities across providers.
+  Fix GPT-5.6 model family names in the OpenAI registry (`gpt` to
+  `gpt-sol`, `gpt-nano` to `gpt-luna`, `gpt-mini` to `gpt-terra`).
+  Add OpenAI models (`gpt-5.6-luna`, `gpt-5.6-sol`, `gpt-5.6-terra`)
+  to the AWS Bedrock registry. Update DeepInfra pricing for
+  `DeepSeek-V3` and `Sky-T1-32B-Preview`. Fix Google model knowledge
+  cutoff dates.
+
+* **repl: control the loop with catch & throw** <br>
+  The curses-based REPL input loop now uses `catch(:exit)` and
+  `throw(:exit)` instead of returning the `:exit` symbol and
+  breaking out of the loop. This enables the `/command` syntax
+  without requiring an `:exit` return value to be propagated
+  through a potentially deeply nested call path.
+
+* **repl: replace Ctrl+D with shell-like delete-at-cursor** <br>
+  The curses-based REPL input now treats Ctrl+D as a delete action
+  that removes the character at the current cursor position, matching
+  the shell/Emacs convention where Ctrl+D deletes the character under
+  the cursor instead of signalling end-of-file. The previous Ctrl+D
+  behaviour (exiting the REPL) is superseded by the `/exit` command.
+
+* **repl: switch to 'Thinking' mode after tool return** <br>
+  The curses-based REPL status line now switches to "Thinking" mode
+  after a tool returns, so the user can see the agent is processing
+  the tool result rather than showing a stale tool-call status.
+
+### Fix
+
+* **agent: fix a subtle typo in the ensure clause** <br>
+  Fix a subtle typo in `LLM::Agent` where the deprecated `trace` local
+  variable was given preference over `tracer` (the preferred local name)
+  in an `ensure` clause. The `trace` local was supported for backward
+  compatibility but the ensure clause still referenced `trace` instead of
+  `tracer`, which meant the previous tracer was never restored when the
+  REPL session ended.
+
+* **repl: restore the cursor in the input area** <br>
+  Remove the `Curses.curs_set(0)` call from the REPL redraw method,
+  which was inadvertently hiding the cursor and making it impossible
+  to see the current position in the input area. The input field is
+  now always drawn at its full height so the cursor position is
+  correctly maintained after each redraw.
+
 ## v12.3.1
 
 Changes since `v12.3.0`.

data/README.md

@@ -129,28 +129,56 @@ This feature requires that the [curses](https://github.com/ruby/curses)
 and [kramdown](https://github.com/gettalong/kramdown) libraries are
 installed and available to require.
 
+The TUI displays a status line with a context-usage bar and cost
+counter, a scrollable transcript with markdown rendering, and a
+multi-line input area. The UI stays responsive while the model
+is generating a response.
+
+##### REPL: Agent
+
+A REPL session is started by calling `repl` on any agent
+instance. The session inherits the agent's model, tools,
+skills, and instructions.
+
 ```ruby
+require "llm"
+
 llm = LLM.deepseek(key: ENV["KEY"])
 agent = LLM::Agent.new(llm)
 agent.repl
 ```
 
-The read-eval-print loop accepts both `tools` and `skills`
-options that lets you attach additional tools or skills
-for the duration of the session. This is in addition to
-any tools or skills that might already be associated with
-an agent.
+##### REPL: State
+
+The `path:` option accepts a file path where runtime state
+is read from and written to. This lets you resume a
+conversation across REPL sessions.
 
 ```ruby
+require "llm"
+
 llm = LLM.deepseek(key: ENV["KEY"])
 agent = LLM::Agent.new(llm)
-agent.repl(tools: [Debugger], skills: [__dir__])
+agent.repl(path: "session.json")
 ```
 
-A number of optional tools are distributed as part
-of llm.rb. They power the agents that can be found in
-the [agents/](agents/) directory, so they're optimized
-for developer tasks.
+##### REPL: Tools
+
+The `tools` option lets you attach additional tools
+for the duration of the session. This is in addition to
+any tools that might already be associated with an agent.
+
+A number of optional tools are distributed as part of
+llm.rb. They power the agents that can be found in the
+[agents/](agents/) directory.
+
+```ruby
+require "llm"
+
+llm = LLM.deepseek(key: ENV["KEY"])
+agent = LLM::Agent.new(llm)
+agent.repl(tools: [Debugger])
+```
 
 The following example starts a read-eval-print loop
 with all of the builtin tools available.
@@ -164,18 +192,77 @@ agent = LLM::Agent.new(llm)
 agent.repl(tools: LLM::Tool.subclasses)
 ```
 
-By default the tracer is disabled for the duration of
-the session. This can be configured through the
-`tracer` option. Setting it to `true` will configure
-the REPL to use the tracer associated with an instance
-of [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
+##### REPL: Skills
+
+The `skills` option lets you load extra skill directories
+without attaching them to an agent permanently.
 
 ```ruby
+require "llm"
+
 llm = LLM.deepseek(key: ENV["KEY"])
-agent = LLM::Agent.new(llm, tracer: LLM.logger(llm, path: "agent.log"))
+agent = LLM::Agent.new(llm)
+agent.repl(skills: [__dir__])
+```
+
+##### REPL: Tracer
+
+By default the tracer is disabled for the duration of the
+session. Setting `tracer: true` configures the REPL to use
+the tracer associated with an instance of
+[`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html).
+
+```ruby
+require "llm"
+
+llm    = LLM.deepseek(key: ENV["KEY"])
+tracer = LLM.logger(llm, path: "agent.log")
+agent  = LLM::Agent.new(llm, tracer:)
 agent.repl(tracer: true, tools: [Debugger])
 ```
 
+##### REPL: Commands
+
+Commands are recognized by a `/` prefix and are backed by the
+[`LLM::Repl::Command`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Command.html)
+class, which can be subclassed to add custom commands. Once you
+create a subclass, it is automatically added to the repl. A command
+can have zero or more parameters, and all parameters are presumed
+to be a String (at least for now).
+
+```ruby
+require "llm"
+require "llm/repl"
+
+class Greeter < LLM::Command
+  name "greet"
+  description "Greets the given name"
+  parameter :name, String, "The person's name"
+  required %i[name]
+
+  def call(name:)
+    write("Welcome #{name}!\n")
+  end
+end
+```
+
+##### REPL: Input
+
+The input area supports several keyboard shortcuts:
+
+| Key | Action |
+|---|---|
+| `Enter` | Submit the current prompt |
+| `Ctrl+A` | Jump to the start of the line |
+| `Ctrl+E` | Jump to the end of the line |
+| `Ctrl+F` | Move the cursor forward |
+| `Ctrl+K` | Erase from cursor to the end of the line |
+| `Ctrl+Y` | Paste previously killed text |
+| `Ctrl+D` | Delete the character at the cursor |
+| `Left / Right` | Move the cursor |
+| `Up / Down` | Scroll the transcript |
+| `/exit` | Leave the REPL |
+
 #### LLM::MCP
 
 The Model Context Protocol (MCP) has first-class support