llm.rb 12.3.0 → 12.4.0

data/lib/llm/repl/command.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+class LLM::Repl
+  ##
+  # The {LLM::Repl::Command LLM::Repl::Command} class is the superclass
+  # of all read-eval-print loop commands. A command has a name, and a
+  # description. This basic version does not implement parameters. A
+  # command is accessible via the `/` prefix: eg `/exit`.
+  class Command
+    ##
+    # @api private
+    UNDEFINED = Object.new
+
+    ##
+    # Find a command by a name, or by an input string.
+    # @example find by name
+    #  LLM::Repl::Command.find_by(name: "exit")
+    # @example find by input string
+    #  LLM::Repl::Command.find_by(input: "/exit")
+    # @note
+    #  The input string must be prefixed with "/"
+    #  or it won't be matched. The match is made
+    #  against the string before the first space -
+    #  so "/exit foo" will match the "exit" command
+    #  but "/exitnow" will not.
+    # @param [String] input
+    # @param [String] name
+    # @return [LLM::Repl::Command, nil]
+    def self.find_by(input: nil, name: nil)
+      if input
+        return nil unless input[0] == "/"
+        n, = input.split(" ")
+        registry.find { n[1..] == _1.name }
+      elsif name
+        registry.find { name == _1.name }
+      else
+        raise ArgumentError, "provide one of: input, name"
+      end
+    end
+
+    ##
+    # @param [LLM::Repl::Command] command
+    #  A new subclass
+    # @return [void]
+    def self.inherited(command)
+      LLM.lock(:inherited) do
+        registry << command
+      end
+    end
+
+    ##
+    # @return [Array<LLM::Repl::Command]
+    def self.registry
+      @registry ||= []
+    end
+
+    ##
+    # Set or get a command name.
+    # @param [String] name
+    #  The command name.
+    # @return [String]
+    def self.name(name = UNDEFINED)
+      return @name if name == UNDEFINED
+      @name = name
+    end
+
+    ##
+    # Set or get a command description.
+    # @param [String] description
+    #  The command description.
+    # @return [String]
+    def self.description(description = UNDEFINED)
+      return @description if description == UNDEFINED
+      @description = description
+    end
+
+    ##
+    # This method should be implemented by subclasses.
+    # @raise [NotImplementedError]
+    def call(...)
+      raise NotImplementedError, "#{self.class}#call is not implemented"
+    end
+    require_relative "commands/exit"
+  end
+end

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

@@ -0,0 +1,19 @@
+# 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
+end

data/lib/llm/repl/input.rb

@@ -6,15 +6,37 @@ 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
     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 +48,64 @@ 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 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 +128,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 +173,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 +212,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 +239,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

@@ -34,7 +34,7 @@ class LLM::Repl
       if error
         @_queue.push [:status, "tool not found: #{tool.name}"]
       else
-        @_queue.push [:status, "tool: #{tool.name}"]
+        @_queue.push [:status, "#{tool.name}(#{format_args(tool)})"]
       end
     end
 
@@ -43,7 +43,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, "Thinking"]
     end
 
     ##
@@ -52,5 +52,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,9 +46,8 @@ class LLM::Repl
     ##
     # @return [void]
     def redraw
-      Curses.clear
-      draw_divider(offset: 5)
       draw_status(offset: input.height + 1)
+      draw_divider(offset: 5)
       draw_transcript(offset: 0)
       draw_input
       Curses.refresh
@@ -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
 
@@ -122,6 +144,11 @@ class LLM::Repl
           Curses.attroff(attrs) if attrs
         end
       end
+      last_drawn = offset + rows.size
+      (last_drawn...self.rows).each do |line|
+        Curses.setpos(line, 0)
+        Curses.clrtoeol
+      end
     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:)
+      @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
@@ -97,6 +103,25 @@ module LLM
 
     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? or !File.exist?(path)
+        agent
+      elsif path?
+        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,22 +129,38 @@ 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]
+        command.call
+      in [:input, String => text]
+        window.scroll_to_bottom
+        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:)
+          agent.save(path:) if path?
+          @queue << [:done]
+        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)
+      command ? [:command, command.new] : [:input, text]
+    end
+
     ##
     # This method reads from the queue that is written to
     # by a second thread. The queue is managed or written
@@ -152,8 +193,19 @@ module LLM
     rescue ThreadError
     end
 
+    ##
+    # @return [Boolean]
+    def path?
+      return false if path.nil?
+      File.readable?(path) and File.writable?(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/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