llm.rb 12.3.1 → 12.5.0

data/lib/llm/repl/commands/exit.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The 'exit' command exits the read-eval-print loop
+  # by throwing. The {LLM::Repl LLM::Repl} class covers
+  # the loop with a catch that gracefully recovers and
+  # exits the loop.
+  class Command::Exit < Command
+    name "exit"
+    description "exits the repl"
+
+    ##
+    # @return [void]
+    def call
+      throw(:exit)
+    end
+  end
+
+  class Command::Quit < Command::Exit
+    name "quit"
+  end
+end

data/lib/llm/repl/commands/help.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  class Help < Command
+    name "help"
+    description "show help for a given command"
+    parameter :name, String, "The name of a command"
+
+    ##
+    # @param [String] name
+    # @return [void]
+    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
+end

data/lib/llm/repl/input.rb

@@ -6,15 +6,38 @@ class LLM::Repl
   # the editable input line shown at the bottom of the REPL.
   # @api private
   class Input
-    CTRL_A    = 1
-    CTRL_E    = 5
+    CTRL = {
+      A: Curses::KEY_CTRL_A,
+      E: Curses::KEY_CTRL_E,
+      F: Curses::KEY_CTRL_F,
+      K: Curses::KEY_CTRL_K,
+      Y: Curses::KEY_CTRL_Y,
+      D: Curses::KEY_CTRL_D
+    }
+
     UP        = Curses::Key::UP
     DOWN      = Curses::Key::DOWN
     LEFT      = Curses::Key::LEFT
     RIGHT     = Curses::Key::RIGHT
+    ESC       = 27
     ENTER     = [Curses::Key::ENTER, 10, 13]
     BACKSPACE = [Curses::Key::BACKSPACE, 127]
-    EOF       = [4]
+
+    ##
+    # Threshold in seconds. If characters arrive faster than
+    # this, we assume the user is pasting multi-line text.
+    # Human typing is ~150–300ms per key, so 50ms reliably
+    # distinguishes a paste from manual typing.
+    PASTE_THRESHOLD = 0.05
+
+    ##
+    # @return [String]
+    attr_reader :buffer
+
+    ##
+    # @param [Boolean] bool
+    # @return [void]
+    attr_writer :paste
 
     ##
     # @param [LLM::Agent] agent
@@ -26,44 +49,66 @@ class LLM::Repl
       @cursor = 0
       @scroll = 0
       @height = options.fetch(:height, 3)
+      @last_char_at = nil
+      @paste = false
     end
 
     ##
     # @param [LLM::Repl::Window] window
     # @param [Object] char
     # @return [Symbol, nil]
-    def on_char(window, char)
-      if EOF.include?(char)
-        :exit
-      elsif BACKSPACE.include?(char)
-        backspace
-        :backspace
-      elsif ENTER.include?(char)
-        :submit
-      elsif char == UP
-        window.scroll_up
-        :up
-      elsif char == DOWN
-        window.scroll_down
-        :down
-      elsif char == CTRL_A
+    def on_char(window, char, now)
+      is_paste = lambda { @last_char_at and (now - @last_char_at) < PASTE_THRESHOLD }
+      if ESC == char
+        @agent.cancel!
+      elsif CTRL[:D] == char
+        delete
+        :ctrl_d
+      elsif CTRL[:A] == char
         move_start
         :ctrl_a
-      elsif char == CTRL_E
+      elsif CTRL[:E] == char
         move_end
         :ctrl_e
+      elsif CTRL[:F] == char
+        move_forward
+        :ctrl_f
+      elsif CTRL[:Y] == char
+        restore
+        :ctrl_y
+      elsif CTRL[:K] == char
+        kill
+        :ctrl_k
       elsif char == LEFT
         move_left
         :left
       elsif char == RIGHT
         move_right
         :right
+      elsif BACKSPACE.include?(char)
+        backspace
+        :backspace
+      elsif ENTER.include?(char)
+        if @paste = is_paste.()
+          insert("\n")
+          :char
+        else
+          :submit
+        end
+      elsif char == UP
+        window.scroll_up
+        :up
+      elsif char == DOWN
+        window.scroll_down
+        :down
       elsif String === char
         insert(char)
         :char
       else
         nil
       end
+    ensure
+      @last_char_at = now if char
     end
 
     ##
@@ -86,27 +131,25 @@ class LLM::Repl
 
     ##
     # Returns the visible lines of the input buffer,
-    # wrapped at the given column width. The viewport
-    # follows the cursor so the cursor line is always
-    # visible.
-    # @param [Integer] cols
+    # split by newlines. The viewport follows the cursor
+    # so the cursor line is always visible.
     # @return [Array<String>]
-    def lines(cols)
-      sync_scroll(cols)
-      text = to_s
-      chunks = text.chars.each_slice(cols).map(&:join)
-      chunks = [""] if chunks.empty?
+    def lines
+      scroll!
+      chunks = to_s.split("\n", -1)
       chunks[@scroll, height] || []
     end
 
     ##
     # Returns the cursor position as [line, column] within
     # the visible viewport.
-    # @param [Integer] cols
     # @return [Array(Integer, Integer)]
-    def cursor_pos(cols)
-      sync_scroll(cols)
-      [(cursor / cols) - @scroll, cursor % cols]
+    def cursor_pos
+      scroll!
+      before = to_s[0...cursor]
+      line  = before.count("\n")
+      col   = cursor - (before.rindex("\n") || -1) - 1
+      [line - @scroll, col]
     end
 
     ##
@@ -133,6 +176,35 @@ class LLM::Repl
       @cursor = [@cursor + 1, @buffer.size].min
     end
 
+    ##
+    # @return [void]
+    def move_forward
+      @cursor = [0, @cursor + 1].max
+    end
+
+    ##
+    # @return [void]
+    def kill
+      @copy = @buffer.slice(@cursor, @buffer.size)
+      @buffer[@cursor, @buffer.size] = ""
+      @cursor = @buffer.size
+    end
+
+    ##
+    # @return [void]
+    def delete
+      @buffer[@cursor] = ""
+      @cursor = [0, @cursor].max
+    end
+
+    ##
+    # @return [void]
+    def restore
+      return unless @copy
+      @buffer.insert(@cursor, @copy)
+      @cursor += @copy.size
+    end
+
     ##
     # @return [String]
     def take
@@ -143,14 +215,20 @@ class LLM::Repl
       end
     end
 
+    ##
+    # @return [Boolean]
+    def paste?
+      @paste
+    end
+
     private
 
     ##
     # Adjusts @scroll so the cursor line is visible within
     # the viewport.
-    def sync_scroll(cols)
-      total_lines = [1, (to_s.length.to_f / cols).ceil].max
-      cursor_line = cursor / cols
+    def scroll!(total_lines = nil)
+      total_lines ||= to_s.split("\n", -1).size
+      cursor_line = to_s[0...cursor].count("\n")
       if cursor_line < @scroll
         @scroll = cursor_line
       elsif cursor_line >= (@scroll + height)
@@ -164,8 +242,13 @@ class LLM::Repl
     end
 
     def insert(char)
+      if lines[-1].size >= Curses.cols
+        @buffer.insert(@cursor, "\n")
+        @cursor += 1
+      end
       @buffer.insert(@cursor, char)
       @cursor += char.length
+      scroll!
     end
 
     def backspace

data/lib/llm/repl/stream.rb

@@ -28,14 +28,9 @@ class LLM::Repl
 
     ##
     # @param [LLM::Function] tool
-    # @param [LLM::Function::Return, nil] error
     # @return [void]
-    def on_tool_call(tool, error)
-      if error
-        @_queue.push [:status, "tool not found: #{tool.name}"]
-      else
-        @_queue.push [:status, "tool: #{tool.name}"]
-      end
+    def on_tool_call(tool)
+      @_queue.push [:status, "#{tool.name}(#{format_args(tool)})"]
     end
 
     ##
@@ -43,7 +38,7 @@ class LLM::Repl
     # @param [LLM::Function::Return] result
     # @return [void]
     def on_tool_return(_tool, result)
-      @_queue.push [:status, "tool done: #{result.name}"]
+      @_queue.push [:status, @repl.thinking_text]
     end
 
     ##
@@ -52,5 +47,45 @@ class LLM::Repl
     def empty!
       @buffer.clear
     end
+
+    private
+
+    ##
+    # Formats tool arguments as compact key: value pairs
+    # suitable for the status line.  Strings are quoted and
+    # truncated, arrays show their first two elements, and
+    # hashes collapse to `{…}`.  The whole string is capped
+    # so it fits alongside the context-usage bar.
+    # @param [LLM::Function] tool
+    # @param [Integer] max
+    # @return [String]
+    def format_args(tool, max: 50)
+      args = tool.arguments
+      pairs = args.to_h.map { "#{_1}: #{format_value(_2)}" }
+      result = pairs.join(", ")
+      result.size > max ? "#{result[0...max - 1]}…" : result
+    end
+
+    ##
+    # @param [Object] value
+    # @param [Integer] max
+    # @return [String]
+    def format_value(value, max: 18)
+      case value
+      when String
+        value.size > max ? "#{value[0...max]}…".inspect : value.inspect
+      when Array
+        items = value.take(2).map { format_value(_1, max: 10) }
+        items << "…" if value.size > 2
+        "[#{items.join(", ")}]"
+      when Hash
+        "{…}"
+      when nil
+        "nil"
+      else
+        str = value.inspect
+        str.size > max ? "#{str[0...max]}…" : str
+      end
+    end
   end
 end

data/lib/llm/repl/transcript.rb

@@ -75,6 +75,12 @@ class LLM::Repl
       @offset = [@offset - 1, 0].max
     end
 
+    ##
+    # @return [void]
+    def scroll_to_bottom
+      @offset = 0
+    end
+
     ##
     # @param [Integer] height
     # @return [Array<String>]

data/lib/llm/repl/window.rb

@@ -46,7 +46,6 @@ class LLM::Repl
     ##
     # @return [void]
     def redraw
-      Curses.curs_set(0)
       draw_status(offset: input.height + 1)
       draw_divider(offset: 5)
       draw_transcript(offset: 0)
@@ -66,6 +65,24 @@ class LLM::Repl
       Curses.getch
     end
 
+    ##
+    # Drains all available characters from the terminal input
+    # buffer without blocking.  Used in place of `Curses.getstr`
+    # when the paste flag is set, so that a huge multi-line
+    # paste is consumed in a single shot instead of being
+    # processed character-by-character.
+    # @return [String]
+    def read_paste
+      chars = +""
+      loop do
+        ch = Curses.getch
+        break unless ch and ch != -1
+        chars << ch
+      end
+      input.paste = false
+      chars
+    end
+
     ##
     # @return [void]
     def scroll_up
@@ -78,6 +95,12 @@ class LLM::Repl
       transcript.scroll_down
     end
 
+    ##
+    # @return [void]
+    def scroll_to_bottom
+      transcript.scroll_to_bottom
+    end
+
     private
 
     def draw_status(offset:)
@@ -99,14 +122,13 @@ class LLM::Repl
     end
 
     def draw_input
-      cols = columns
-      rows = input.lines(cols)
-      rows.each.with_index do |line, idx|
+      rows = input.lines
+      (0...input.height).each do |idx|
         Curses.setpos((Curses.lines - input.height) + idx, 0)
         Curses.clrtoeol
-        Curses.addstr(line)
+        Curses.addstr(rows[idx]) if idx < rows.length
       end
-      line, col = input.cursor_pos(cols)
+      line, col = input.cursor_pos
       Curses.setpos((Curses.lines - input.height) + line, col)
     end
 

data/lib/llm/repl.rb

@@ -22,16 +22,20 @@ module LLM
     require_relative "repl/bar"
     require_relative "repl/stream"
     require_relative "repl/markdown"
+    require_relative "repl/command"
 
     ##
     # @param [LLM::Agent] agent
+    # @param [String, nil] path
+    #  The path where to maintain runtime state
     # @param [Array<LLM::Tool>] tools
     #  Zero or more tools
     # @param [Array<String>] skills
     #  Zero or more skills
     # @return [LLM::Repl]
-    def initialize(agent:, tools:, skills:)
-      @agent = agent
+    def initialize(agent:, tools: [], skills: [], path: nil)
+      @path  = path
+      @agent = configure(agent:, path:)
       @provider = agent.llm.name
       @status = Status.new(@agent)
       @transcript = Transcript.new
@@ -56,15 +60,17 @@ module LLM
     # @return [void]
     def start
       window.open do
-        loop do
-          case input.on_char(window, window.getch)
-          when :exit then break
-          when :submit then submit
-          when :up, :down, :backspace, :char then window.redraw
-          else
-            window.redraw
-            read!
-            sleep 0.01
+        catch(:exit) do
+          loop do
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            case input.on_char(window, input.paste? ? window.read_paste : window.getch, now)
+            when :submit then submit
+            when Symbol then window.redraw
+            else
+              window.redraw
+              read!
+              sleep 0.01
+            end
           end
         end
       end
@@ -95,8 +101,36 @@ module LLM
       window.redraw
     end
 
+    ##
+    # @return [String]
+    def thinking_text
+      "thinking • Esc to cancel"
+    end
+
     private
 
+    ##
+    # @param [LLM::Agent] agent
+    #  An agent
+    # @param [String] path
+    #  A path
+    # @raise [LLM::Error]
+    #  When given an unusable path
+    # @return [LLM::Agent]
+    def configure(agent:, path:)
+      if path.nil?
+        agent
+      elsif !File.exist?(path)
+        File.write path, "{}"
+        agent
+      elsif restore?
+        agent.restore(path:)
+      else
+        raise LLM::Error, "I can't use '#{path}' - " \
+                          "it should be both readable and writable"
+      end
+    end
+
     ##
     # This method is called when the user submits their input.
     # It spawns a second thread that maintains a line of
@@ -104,19 +138,58 @@ module LLM
     # the UI runs - remains responsive.
     # @api private
     def submit
-      return if thread&.alive?
-      text = input.take
-      return if text.empty?
-      status.text = "thinking"
-      write("user: ", Curses::A_BOLD)
-      markdown(text)
-      write("\nagent: ", Curses::A_BOLD)
-      @thread = Thread.new do
-        @queue << [:start]
-        agent.talk(text, tools:, stream:)
-        @queue << [:done]
-      rescue => e
-        @queue << [:error, e]
+      return if thread&.alive? || (text = input.take).empty?
+      case on_text(text)
+      in [:command, Command => command, Hash => parameters]
+        command.call(**parameters)
+      in [:error, String => who, String => text]
+        write(who, Curses::A_BOLD)
+        write(text)
+      in [:input, String => text]
+        window.scroll_to_bottom
+        status.text = thinking_text
+        write("user: ", Curses::A_BOLD)
+        markdown(text)
+        write("\nagent: ", Curses::A_BOLD)
+        @thread = Thread.new do
+          @queue << [:start]
+          agent.talk(text, tools:, stream:)
+          agent.save(path:) if save?
+          @queue << [:done]
+        rescue LLM::Interrupt => e
+          @queue << [:cancel, e]
+        rescue => e
+          @queue << [:error, e]
+        end
+      end
+    end
+
+    ##
+    # Receives user input and determines what codepath
+    # it should follow - either executing a command,
+    # or sending a string to the model.
+    # @param [String] text
+    # @return [[Symbol, Command|String]]
+    def on_text(text)
+      command = Command.find_by(input: text)
+      if command
+        parameters = command.parameters.map { [_1, _2.dup] }.to_h
+        args = text.split(" ")[1..].reject(&:empty?)
+        reqc = parameters.values.count(&:required?)
+        if args.size < reqc
+          [:error,
+           "command(#{command.name}): ",
+           "too few arguments: expected #{reqc} but got #{args.size}\n\n"]
+        else
+          parameters.each_value do |parameter|
+            if args[parameter.index]
+              parameter.value = args[parameter.index]
+            end
+          end
+          [:command, command.new(self), parameters.transform_values(&:value)]
+        end
+      else
+        [:input, text]
       end
     end
 
@@ -138,22 +211,47 @@ module LLM
           self.status = value
         when :done
           status.text = "idle"
-          @thread = nil
+          write("\n\n")
           transcript.finish
+          @thread = nil
+        when :cancel
+          status.text = "Idle"
+          write("\n\nagent: ", Curses::A_BOLD)
+          write("request cancelled!")
           write("\n\n")
+          transcript.finish
+          @thread = nil
         when :error
           # Do this better
           status.text = "error"
-          transcript.finish
           write("\nerror: #{value.message}\n", Curses::A_BOLD)
+          transcript.finish
           @thread = nil
         end
       end
     rescue ThreadError
     end
 
+    ##
+    # @return [Boolean]
+    def restore?
+      return false if path.nil?
+      File.writable?(path)
+    end
+
+    ##
+    # @return [Boolean]
+    def save?
+      return false if path.nil?
+      File.readable?(path)
+    end
+
     attr_reader :agent, :provider, :stream,
                 :status, :transcript, :input,
-                :window, :tools, :thread
+                :window, :tools, :thread,
+                :path
+
+    File = ::File
+    private_constant :File
   end
 end

data/lib/llm/stream.rb

@@ -114,20 +114,15 @@ module LLM
     #   `ctx.spawn(tool, :fiber)`, or `ctx.spawn(tool, :task)` onto {#queue}.
     #   Mixed strategies can also be selected per tool, such as
     #   `tool.mcp? ? ctx.spawn(tool, :task) : ctx.spawn(tool, :ractor)`.
-    #   When a streamed tool cannot be resolved, `error` is passed as an
-    #   {LLM::Function::Return}. It can be sent back to the model, allowing
-    #   the tool-call path to recover and the session to continue. Streamed
-    #   tool resolution now prefers the current request tools, so
+    #   Streamed tool resolution now prefers the current request tools, so
     #   {LLM.function}, MCP tools, bound tool instances, and normal
     #   {LLM::Tool LLM::Tool} classes can all resolve through the same
     #   request-local path. The current `:ractor` mode is for class-based
     #   tools and does not support MCP tools.
     # @param [LLM::Function] tool
     #  The parsed tool call.
-    # @param [LLM::Function::Return, nil] error
-    #  An in-band tool error for unresolved tool calls.
     # @return [nil]
-    def on_tool_call(tool, error)
+    def on_tool_call(tool)
       nil
     end
 

data/lib/llm/tools/ls.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class LLM::Tool
+  ##
+  # The {LLM::Tool::Ls LLM::Tool::Ls} class implements
+  # a tool that can list files and directories, with an
+  # optional glob pattern to filter results.
+  class Ls < self
+    name "ls"
+    description "list files and directories, optionally matching a glob pattern"
+    parameter :path, String, "the directory to list (default is cwd)"
+    parameter :glob, String, "an optional glob pattern (e.g. '*.rb', '**/*.md')"
+
+    ##
+    # @param [String] path
+    # @param [String, nil] glob
+    # @return [Hash]
+    def call(path: Dir.getwd, glob: "*")
+      validate!(path:)
+      entries = Dir.glob(File.join(path, glob))
+      {ok: true, entries:, count: entries.size}
+    end
+
+    private
+
+    def validate!(path:)
+      raise "path does not exist: #{path}" unless Dir.exist?(path)
+    end
+  end
+end