llm.rb 13.1.0 → 15.0.0

data/lib/llm/repl/node.rb

@@ -23,6 +23,13 @@ class LLM::Repl
       @attrs = attrs
     end
 
+    ##
+    # @return [Integer]
+    def size
+      @text.size
+    end
+    alias_method :length, :size
+
     ##
     # Hash-like lookup.
     # @param [Symbol] key

data/lib/llm/repl/status.rb

@@ -4,38 +4,87 @@ class LLM::Repl
   ##
   # The {LLM::Repl::Status LLM::Repl::Status} class stores
   # the small status line shown at the top of the REPL.
+  #
+  # The status text can be a plain String, a single
+  # {LLM::Repl::Node LLM::Repl::Node} (text plus curses attributes),
+  # or an Array of either. Attributes on nodes are applied when the
+  # window draws the status line.
   # @api private
   class Status
     ##
     # @param [LLM::Repl] repl
     # @return [LLM::Repl::Status]
     def initialize(repl)
+      @repl = repl
       @agent = repl.agent
       @provider = @agent.llm.name
-      @text = "idle"
+      @nodes = [Node.new("idle")]
     end
 
     ##
     # @return [String]
     def context_bar
       LLM::Repl::Bar.new(
-        used: @agent.usage.total_tokens,
-        total: @agent.context_window
+        ##
+        # After compaction the used context is unknown until the next
+        # response, so the bar renders an unknown state instead of a
+        # stale percentage.
+        fraction: @agent.compacted? ? nil : @agent.context_usage
       ).to_s
     end
 
     ##
     # @return [String]
     def cost
-      "$#{@agent.cost}"
+      "$#{@agent.cost} "
+    end
+
+    ##
+    # Returns the current model in use.
+    # @return [LLM::Repl::Node]
+    def model
+      Node.new @repl.model.to_s, Curses::A_BOLD
+    end
+
+    ##
+    # Returns the current working directory.
+    # @return [LLM::Repl::Node]
+    def cwd
+      Node.new Dir.pwd.sub(Dir.home, "~"), Curses::A_BOLD
+    end
+
+    ##
+    # Sets the status text.
+    # @param [String, LLM::Repl::Node, Array<String, LLM::Repl::Node>] value
+    # @return [Array<LLM::Repl::Node>]
+    def text=(value)
+      @nodes =
+        case value
+        when Node then [value]
+        when Array then value.map { |node| Node === node ? node : Node.new(node) }
+        else [Node.new(value)]
+        end
     end
 
     ##
     # @return [String]
-    attr_accessor :text
+    def text
+      @nodes.map(&:text).join
+    end
 
     ##
     # @return [String]
     alias_method :to_s, :text
+
+    ##
+    # The nodes making up the status line.
+    # @return [Array<LLM::Repl::Node>]
+    def nodes
+      if @agent.compacted?
+        [Node.new("Context compacted")]
+      else
+        @nodes
+      end
+    end
   end
 end

data/lib/llm/repl/stream.rb

@@ -8,6 +8,10 @@ class LLM::Repl
   # tool returns.
   # @api private
   class Stream < LLM::Stream
+    ##
+    # @return [Hash<Symbol, LLM::Tool>]
+    attr_reader :tools
+
     ##
     # @param [LLM::Repl] repl
     # @return [LLM::Repl::Stream]
@@ -15,6 +19,7 @@ class LLM::Repl
       @repl = repl
       @_queue = queue
       @buffer = +""
+      @tools = {}
     end
 
     ##
@@ -30,15 +35,16 @@ class LLM::Repl
     # @param [LLM::Function] tool
     # @return [void]
     def on_tool_call(tool)
-      @_queue.push [:status, "#{tool.name}(#{format_args(tool)})"]
+      @tools[tool.name] = tool
+      @_queue.push [:status, [" ", lambda, " • #{tool.name}(#{format_args(tool)})"]]
     end
 
     ##
-    # @param [LLM::Function] _tool
+    # @param [LLM::Function] tool
     # @param [LLM::Function::Return] result
     # @return [void]
-    def on_tool_return(_tool, result)
-      @_queue.push [:status, @repl.thinking_text]
+    def on_tool_return(tool, result)
+      @tools.delete(tool.name)
     end
 
     ##
@@ -50,6 +56,12 @@ class LLM::Repl
 
     private
 
+    ##
+    # @return [LLM::Repl::Node]
+    def lambda
+      Node.new("λ", Curses::A_BOLD | Color.red)
+    end
+
     ##
     # Formats tool arguments as compact key: value pairs
     # suitable for the status line.  Strings are quoted and

data/lib/llm/repl/walker.rb

@@ -18,12 +18,13 @@ class LLM::Repl
     end
 
     ##
-    # @return [Object, nil]
+    # @return [Object, String, nil]
     def next
       if @items.empty?
         nil
       elsif @cursor >= @items.size - 1
-        @items[@cursor]
+        @cursor = @items.size
+        ""
       else
         @cursor += 1
         @items[@cursor]

data/lib/llm/repl/window.rb

@@ -6,6 +6,11 @@ class LLM::Repl
   # curses screen for the REPL.
   # @api private
   class Window
+    ##
+    # Rows reserved for the top chrome (the blue model/cwd row).
+    # @api private
+    TOP_ROWS = 1
+
     ##
     # @return [LLM::Repl::Status]
     attr_reader :status
@@ -23,6 +28,7 @@ class LLM::Repl
     #  A read-eval-print loop.
     # @return [LLM::Repl::Window]
     def initialize(repl)
+      @repl   = repl
       @status = repl.status
       @buffer = repl.buffer
       @input  = repl.input
@@ -33,21 +39,25 @@ class LLM::Repl
     # @return [void]
     def open
       Curses.init_screen
+      Color.enable
       Curses.cbreak
       Curses.noecho
       Curses.stdscr.keypad(true)
       Curses.stdscr.nodelay = true
+      hide_cursor
       yield
     ensure
+      show_cursor
       Curses.close_screen
     end
 
     ##
     # @return [void]
     def redraw
+      draw_meta(offset: Curses.lines)
       draw_status(offset: input.height + 1)
       draw_divider(offset: 5)
-      draw_buffer(offset: 0)
+      draw_buffer(offset: TOP_ROWS)
       draw_input
       Curses.refresh
     end
@@ -58,6 +68,20 @@ class LLM::Repl
       [Curses.lines - (input.height + 4), 1].max
     end
 
+    ##
+    # @return [Integer]
+    def columns
+      Curses.cols
+    end
+
+    ##
+    # Redraws the window after it has been resized.
+    # @return [void]
+    def resize
+      Curses.clear
+      redraw
+    end
+
     ##
     # @return [Object]
     def getch
@@ -102,43 +126,91 @@ class LLM::Repl
 
     private
 
+    ##
+    # Draws the window's primary content
+    # @return [void]
     def draw_buffer(offset:)
       rows = buffer.visible(self.rows)
-      rows.each.with_index(offset) do |row, index|
+      rows.each.with_index(TOP_ROWS) do |row, index|
         Curses.setpos(index, 0)
         Curses.clrtoeol
+        Curses.setpos(index, gutter)
+        width = 0
         row.each do |chunk|
-          text, attrs = chunk.text, chunk.attrs
+          remaining = buffer.width - width
+          break if remaining <= 0
+          text, attrs = chunk.text.to_s, chunk.attrs
+          clipped = text[0, remaining]
           Curses.attron(attrs) if attrs
-          Curses.addstr(text)
+          Curses.addstr(clipped)
           Curses.attroff(attrs) if attrs
+          width += clipped.length
         end
       end
       last_drawn = offset + rows.size
-      (last_drawn...self.rows).each do |line|
+      (last_drawn...(Curses.lines - 5)).each do |line|
         Curses.setpos(line, 0)
         Curses.clrtoeol
       end
     end
 
+    ##
+    # Draws the status line
+    # @return [void]
     def draw_status(offset:)
-      Curses.setpos(Curses.lines - offset, 0)
+      y = Curses.lines - offset
+      Curses.setpos(y, 0)
       Curses.clrtoeol
-      Curses.addstr(status.to_s)
+      status.nodes.each { addnode(_1) }
       context = status.context_bar
-      Curses.setpos(Curses.lines - offset, [(columns - context.length) / 2, 0].max)
+      Curses.setpos(y, [(columns - context.length) / 2, 0].max)
       Curses.addstr(context)
       cost = status.cost.to_s
-      Curses.setpos(Curses.lines - offset, [columns - cost.length, 0].max)
+      Curses.setpos(y, [columns - cost.length, 0].max)
       Curses.addstr(cost)
     end
 
+    ##
+    # Draws the top chrome row (model left, cwd right) at the very top
+    # of the screen, with a blue background.
+    # @param [Integer] offset
+    # @return [void]
+    def draw_meta(offset:)
+      y = Curses.lines - offset
+      fill_row(y) do
+        addnode(status.cwd, status.cwd.text[0, columns])
+        Curses.setpos(y, [columns - status.model.text.size, 0].max)
+        addnode(status.model, status.model.text[0, columns])
+      end
+    end
+
+    ##
+    # Fills an entire row with the status-bar background color, then
+    # draws the given content on top (which inherits the blue
+    # background), and resets the background afterwards.
+    # @param [Integer] y
+    # @yield Content to draw on the row
+    # @return [void]
+    def fill_row(y, &)
+      Curses.setpos(y, 0)
+      Curses.bkgdset(Color.statusbar)
+      Curses.clrtoeol
+      yield
+      Curses.bkgdset(0)
+    end
+
+    ##
+    # Draws a horiztonal line
+    # @return [void]
     def draw_divider(offset:)
       Curses.setpos(Curses.lines - offset, 0)
       Curses.clrtoeol
       Curses.addstr("─" * Curses.cols)
     end
 
+    ##
+    # Draws the input area
+    # @return [void]
     def draw_input
       rows = input.lines
       (0...input.height).each do |idx|
@@ -148,12 +220,40 @@ class LLM::Repl
       end
       line, col = input.cursor_pos
       Curses.setpos((Curses.lines - input.height) + line, col)
+      show_cursor
     end
 
     ##
+    # Hides the cursor.
+    # @return [void]
+    def hide_cursor
+      Curses.curs_set(0)
+    end
+
+    ##
+    # Shows the cursor.
+    # @return [void]
+    def show_cursor
+      Curses.curs_set(1)
+    end
+
+    ##
+    # 20% offset that occupies the left margin and
+    # helps center {LLM::Repl::Buffer LLM::Repl::Buffer}.
     # @return [Integer]
-    def columns
-      Curses.cols
+    def gutter
+      (columns * 0.2).floor
+    end
+
+    ##
+    # Adds a {LLM::Repl::Node} to the Curses window.
+    # @param [LLM::Repl::Node] node
+    # @param [String] text
+    # @return [void]
+    def addnode(node, text = node.text)
+      Curses.attron(node.attrs) if node.attrs
+      Curses.addstr(text)
+      Curses.attroff(node.attrs) if node.attrs
     end
   end
 end

data/lib/llm/repl.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-LLM.require "curses"
-LLM.require "kramdown"
-
 module LLM
   ##
   # The {LLM::Repl LLM::Repl} class provides a small
@@ -15,6 +12,10 @@ module LLM
   # task correctly, or for it to correct course after a
   # mistake was made.
   class Repl
+    LLM.require "curses", "~> 1.6"
+    LLM.require "kramdown", "~> 2.5"
+
+    require_relative "repl/color"
     require_relative "repl/window"
     require_relative "repl/status"
     require_relative "repl/buffer"
@@ -29,7 +30,7 @@ module LLM
     attr_reader :agent, :provider, :stream,
                 :status, :buffer, :input,
                 :window, :tools, :thread,
-                :name, :path, :width
+                :name, :path
 
     ##
     # @param [LLM::Agent] agent
@@ -43,14 +44,15 @@ module LLM
     #  Zero or more skills
     # @return [LLM::Repl]
     def initialize(agent:, name: nil, tools: [], skills: [], path: nil)
-      @width = 80
       @path = path
       @name = name || "agent"
+      @sender = "You"
       @agent = configure(agent:, path:)
       @provider = agent.llm.name
-      @status = Status.new(self)
-      @buffer = Buffer.new(self)
+      @model = agent.model
       @input = Input.new(self, height: 3)
+      @buffer = Buffer.new(self)
+      @status = Status.new(self)
       @window = Window.new(self)
       @thread = nil
       @queue = Queue.new
@@ -112,7 +114,7 @@ module LLM
     # @param [String] chars
     # @return [Array<Node>]
     def markdown(chars)
-      LLM::Repl::Markdown.new(chars, width).ast
+      LLM::Repl::Markdown.new(chars, buffer.width).ast
     end
 
     ##
@@ -125,8 +127,34 @@ module LLM
 
     ##
     # @return [String]
-    def thinking_text
-      "thinking • Esc to cancel"
+    def think_text
+      " 🧠 • Thinking • Esc to cancel"
+    end
+
+    ##
+    # @return [String]
+    def connect_text
+      " 🌐 • Connecting • Esc to cancel"
+    end
+
+    ##
+    # Returns a label for the person who sent a message.
+    # @return [String]
+    def sender
+      @sender
+    end
+
+    ##
+    # Returns the active model.
+    # @return [String]
+    def model
+      @model
+    end
+
+    ##
+    # Sets the active model.
+    def model=(other)
+      @model = other
     end
 
     private
@@ -138,11 +166,11 @@ module LLM
     def tree(messages)
       messages.flat_map do |message|
         next if message.tool_call? || message.tool_return?
-        user = message.assistant? ? name : "user"
+        user = message.assistant? ? name : sender
         [
-          Node.new("#{user}: ", Curses::A_BOLD),
-          Node.new(message.content),
-          Node.new(user == name ? "\n\n" : "\n")
+          Node.new("#{user}:\n", Curses::A_BOLD | Color.blue),
+          *markdown(message.content),
+          Node.new("\n\n")
         ]
       end.compact
     end
@@ -180,17 +208,15 @@ module LLM
       case on_text(text)
       in [:command, Command => command, Hash => parameters]
         command.call(**parameters)
-        write("\n")
       in [:error, String => user, String => text]
         write_message(user, text)
-        write("\n")
       in [:input, String => text]
         window.scroll_to_bottom
-        status.text = thinking_text
-        write_message("user", markdown(text))
+        status.text = connect_text
+        write_message(sender, markdown(text))
         @thread = Thread.new do
           @queue << [:start]
-          agent.talk(text, tools:, stream:)
+          agent.talk(text, model:, tools:, stream:)
           agent.save(path:) if save?
           @queue << [:done]
         rescue LLM::Interrupt => e
@@ -245,6 +271,7 @@ module LLM
           buffer.open
           stream.clear
         when :stream
+          status.text = think_text if stream.tools.empty?
           write_message name, markdown(value), method: :replace
         when :status
           self.status = value
@@ -252,13 +279,12 @@ module LLM
           status.text = "idle"
           buffer.close
           @thread = nil
-          write("\n")
         when :cancel
+          stream.tools.clear
           buffer.close
           status.text = "Idle"
           write_message(name, "Request cancelled")
           @thread = nil
-          write("\n")
         when :error
           status.text = "error"
           write_message(name, "(#{value.class}): #{value.message}")

data/lib/llm/sequel/plugin.rb

@@ -236,16 +236,30 @@ module LLM::Sequel
     # @return [Integer]
     def context_window
       ctx.context_window
-    rescue LLM::NoSuchModelError, LLM::NoSuchRegistryError
-      0
+    end
+
+    ##
+    # Returns how many tokens have been used
+    # within the context window
+    # @return [Integer]
+    def context_used
+      ctx.context_used
+    end
+
+    ##
+    # Returns context window usage as a Rational
+    # @return [Rational, nil]
+    def context_usage
+      ctx.context_usage
     end
 
     ##
     # Returns usage from the mapped usage columns.
-    # @return [LLM::Object]
-    def usage
-      ctx.usage || LLM::Object.from(input_tokens: 0, output_tokens: 0, total_tokens: 0)
+    # @return [LLM::Usage]
+    def token_usage
+      ctx.token_usage
     end
+    alias_method :usage, :token_usage
 
     ##
     # @see LLM::Context#interrupt!

data/lib/llm/skill.rb

@@ -80,19 +80,25 @@ module LLM
     end
 
     ##
-    # Execute the skill by wrapping it in a small agent with the skill
-    # instructions. The context is bound explicitly by the caller so the
-    # nested agent can inherit context-level behavior such as streaming.
+    # Execute the skill by wrapping it in a small agent
+    # with the skill instructions. The context is bound
+    # explicitly by the caller so the nested agent can
+    # inherit context-level behavior such as streaming.
     # @param [LLM::Context] ctx
     # @return [Hash]
     def call(ctx)
-      content = agent(ctx).talk("Solve the user's query.").content
-      {content:}
+      stream = ctx.stream
+      stream.on_skill_call(self)
+      agent = self.agent(ctx)
+      res = agent.talk("Solve the user's query.")
+      stream.on_skill_return(agent, self, res)
+      {content: res.content}
     end
 
     ##
-    # Expose the skill as a normal LLM::Tool. The context is bound explicitly
-    # when the tool class is built.
+    # Expose the skill as a normal LLM::Tool. The
+    # context is bound explicitly when the tool class
+    # is built.
     # @param [LLM::Context] ctx
     # @return [Class<LLM::Tool>]
     def to_tool(ctx)
@@ -100,7 +106,14 @@ module LLM
       Class.new(LLM::Tool) do
         attr_accessor :tracer
 
-        name skill.name
+        ##
+        # The skill's tool is named "<skill>-skill" so
+        # that it is unique from any tool the skill
+        # itself exposes (or any global tool). Otherwise
+        # a skill named `weather` that uses a `weather`
+        # tool would collide: both resolve to the same
+        # name.
+        name "#{skill.name}-skill"
         description skill.description
 
         define_singleton_method(:skill?) do

data/lib/llm/stream.rb

@@ -128,7 +128,10 @@ module LLM
     ##
     # Called when a streamed tool call has been fully constructed.
     # A stream implementation may start tool execution here by pushing
-    # `@queue << tool.task(:thread)` onto {#queue}.
+    # `@queue << tool.task(:thread).tap(&:spawn)` onto {#queue} — `spawn`
+    # returns nil, so `tap` keeps the task while starting it. The task
+    # carries the context's guard, so it is checked before the tool runs —
+    # a blocked call yields its guard return without executing.
     # @param [LLM::Function] tool
     #  The parsed tool call.
     # @return [nil]
@@ -151,19 +154,17 @@ module LLM
 
     ##
     # Called before a context transformer rewrites a prompt.
-    # @param [LLM::Context] ctx
-    # @param [#call] transformer
+    # @param [LLM::Transformer] transformer
     # @return [nil]
-    def on_transform(ctx, transformer)
+    def on_transform(transformer)
       nil
     end
 
     ##
     # Called after a context transformer finishes rewriting a prompt.
-    # @param [LLM::Context] ctx
-    # @param [#call] transformer
+    # @param [LLM::Transformer] transformer
     # @return [nil]
-    def on_transform_finish(ctx, transformer)
+    def on_transform_finish(transformer)
       nil
     end
 
@@ -183,6 +184,33 @@ module LLM
       nil
     end
 
+    ##
+    # Called when a request is rate limited and will be retried.
+    # @param [LLM::RateLimitError] error
+    # @return [nil]
+    def on_rate_limit(error)
+      nil
+    end
+
+    ##
+    # Called before a skill's subagent runs.
+    # @param [LLM::Skill] skill
+    # @return [nil]
+    def on_skill_call(skill)
+      nil
+    end
+
+    ##
+    # Called after a skill's subagent finishes.
+    # @param [LLM::Agent] agent
+    #  The subagent that ran the skill
+    # @param [LLM::Skill] skill
+    # @param [LLM::Response, nil] result
+    # @return [nil]
+    def on_skill_return(agent, skill, result)
+      nil
+    end
+
     # @endgroup
 
     # @group Finders