elelem 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4696869850fc38fba45a65a38aca74f8663fe9b8562deb7a987cbc71058221a
-  data.tar.gz: 8ec379df1537243659cfee997c02fde40912be780ace54b14bb0ff181f5fad64
+  metadata.gz: f6da2ace697aa7b578edd8144e10eb779677b24e58d62f1a4a4c88ed042c85b0
+  data.tar.gz: ea9e8728d8632514352f34788d200cf8f7f09205e85527ba63b04f5c11fb6c1c
 SHA512:
-  metadata.gz: 52e225e4b206091bcd1838cce432ee2391c648fa4f995a722dfefc2820985bb405e5e3574a972a8e31be260695eb368f3f6f3dcfa32f8cbeeb76b5fab6b1a2f3
-  data.tar.gz: c508bfedce1daf081011046ca77a13872af1bb133d161edfb944d7e4019e92222b15dc9aeb4f98376328e099a62e5ec89f2b67d2f595ed6ea6a58281a0a44589
+  metadata.gz: 874c019ad05cd113e1c68114648834f2b7a420ea9f3bfe07a378766e117def9a15467d80548d470274c81507524fc1ab5379db92843c1ed5dee66efbb14299bd
+  data.tar.gz: 14b4b17556f3fc5830d7579c69b8cbb30048d631135d973aa6368933801e48e3ac3485d3c7b1ba1559b69810d99916a368aa6a860cff3866d1c94df9754ee9e7

data/README.md

@@ -23,24 +23,24 @@ gem install elelem
 
 ## Usage
 
-Start an interactive chat session:
+Start elelem:
 
 ```bash
-elelem chat
+elelem
 ```
 
 ## Tools
 
-Use the plugin API to add tools.
+elelem ships with `read`, `write` and `execute`. Use the plugin API to add more.
 
 ## Contributing
 
 ```bash
-$ git clone https://git.mokhan.ca/elelem/elelem.git
+git clone https://github.com/elelem-sh/elelem.git
 ```
 
 Send me a patch via email. For instructions see https://git-send-email.io/.
 
 ## License
 
-MIT – see the bundled `LICENSE.txt`.
+MIT. See the bundled `LICENSE.txt`.

data/exe/elelem

@@ -3,12 +3,6 @@
 
 require "elelem/cli"
 
-begin
-  require "elelem/builtins"
-rescue LoadError
-  warn "elelem: gem install elelem-builtins for the default tools and commands"
-end
-
 Signal.trap("INT") { exit 1 }
 
 Elelem::CLI.new(ARGV).run

data/lib/elelem/agent.rb

@@ -5,17 +5,18 @@ module Elelem
     attr_reader :conversation, :toolbox, :output
     attr_accessor :provider
 
-    def initialize(provider, toolbox: Toolbox.new, output: NullOutput.new, system_prompt: nil)
+    def initialize(provider, toolbox: Toolbox.new, output: NullOutput.new, template: nil, system_prompt: nil)
       @provider = provider
       @toolbox = toolbox
       @output = output
-      @conversation = Transcript.new(system_prompt: system_prompt)
+      @conversation = Conversation.new(template: template, system_prompt: system_prompt)
     end
 
     def context
       @conversation.to_a
     end
 
+    # A provider error leaves the turn: the caller decides how to report it.
     def turn(prompt)
       @conversation.add(role: "user", content: prompt)
       content = run_until_done([])
@@ -25,64 +26,23 @@ module Elelem
 
     private
 
+    # Tool calls and their results stay out of the conversation: only the
+    # prompt and the final reply are kept.
     def run_until_done(ctx)
       loop do
-        content, tool_calls = fetch_and_say(ctx)
+        content, tool_calls = fetch(ctx)
         return content if tool_calls.empty?
 
-        ctx.concat(tool_turn(content, tool_calls))
+        ctx.push({ role: "assistant", content: content, tool_calls: tool_calls }, *tool_calls.map { |c| process(c) })
       end
     end
 
-    def fetch_and_say(ctx)
+    def fetch(ctx)
       output.waiting
-      content, tool_calls = fetch_response(ctx)
-      output.say(content, as: :markdown)
-      [content, tool_calls]
-    end
-
-    def tool_turn(content, tool_calls)
-      results = tool_calls.map { |tool_call| tool_result(tool_call) }
-      [{ role: "assistant", content: content, tool_calls: tool_calls }.compact, *results]
-    end
-
-    def tool_result(tool_call)
-      { role: "tool", tool_call_id: tool_call[:id], content: process(tool_call).to_json }
-    end
-
-    def process(tool_call)
-      name = tool_call[:name]
-      args = tool_call[:arguments]
-      output.doing(toolbox.tool_for(name).name, args)
-      Elelem.logger.debug("agent: #{name}(#{args.inspect})")
-      log_result(name, toolbox.run(name.to_s, args))
-    end
-
-    def log_result(name, result)
-      Elelem.logger.debug("agent: #{name} -> #{result.inspect}")
-      result
-    end
-
-    def fetch_response(ctx)
-      collect_response(ctx)
-    rescue StandardError, ScriptError => e
-      fetch_error(e)
-    end
-
-    def collect_response(ctx)
-      content = String.new
-      tool_calls = []
-      provider.fetch(messages(ctx), toolbox.to_a) { |event| handle_event(event, content, tool_calls) }
-      [content, tool_calls]
-    end
-
-    def messages(ctx)
-      @conversation.to_a(ctx)
-    end
-
-    def fetch_error(error)
-      warn_and_say(error)
-      ["Error: #{error.message}", []]
+      [String.new, []].tap do |content, tool_calls|
+        provider.fetch(@conversation.to_a(ctx), toolbox.to_a) { |event| handle_event(event, content, tool_calls) }
+        output.say(content, as: :markdown)
+      end
     end
 
     def handle_event(event, content, tool_calls)
@@ -93,9 +53,12 @@ module Elelem
       end
     end
 
-    def warn_and_say(error)
-      Elelem.logger.warn("agent: #{error.message}")
-      output.say(error.message, as: :error)
+    def process(call)
+      name, args = call.values_at(:name, :arguments)
+      output.doing(toolbox.tool_for(name)&.name || "#{name}?", args)
+      result = toolbox.run(name.to_s, args).to_json
+      Elelem.logger.debug("agent: #{name}(#{args.inspect}) -> #{result}")
+      { role: "tool", tool_call_id: call[:id], content: result }
     end
   end
 end

data/lib/elelem/builtins/terminal.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Builtins
+    # Output for a person at a terminal: dots while the model thinks, markdown
+    # through glow, files through bat, and a copy of everything in a private
+    # transcript under $XDG_STATE_HOME/elelem/sessions.
+    class Terminal < Output
+      def initialize(stream: $stdout, **)
+        super
+        @dots_thread = nil
+        @at_line_start = true
+      end
+
+      def say(text, as: nil)
+        stop_dots
+        super
+      end
+
+      def print(text)
+        stop_dots
+        super
+      end
+
+      def doing(name, args, state: "+")
+        gap
+        super
+      end
+
+      def waiting
+        stop_dots
+        @dots_thread = Thread.new do
+          until Thread.current[:stop]
+            @stream.print "."
+            @stream.flush
+            sleep 0.1
+          end
+        end
+      end
+
+      def display_file(path, fallback: nil)
+        system("bat", "--paging=never", "--", path) || super
+      end
+
+      private
+
+      def render(text, as)
+        case as
+        when :error then "\n  x #{text}"
+        when :markdown then markdown(text)
+        else text
+        end
+      end
+
+      def markdown(text)
+        gap
+        width = begin
+          @stream.winsize[1]
+        rescue StandardError
+          80
+        end
+        IO.popen(["glow", "-s", "dark", "-w", width.to_s, "-"], "r+") do |io|
+          io.write(text)
+          io.close_write
+          io.read
+        end
+      rescue Errno::ENOENT
+        text
+      end
+
+      def gap
+        stop_dots
+        write("\n") unless @at_line_start
+      end
+
+      def stop_dots
+        return unless @dots_thread
+
+        @dots_thread[:stop] = true
+        @dots_thread.join
+        @dots_thread = nil
+        write("\n")
+      end
+
+      def write(text)
+        @stream.print text
+        @at_line_start = text.end_with?("\n")
+        (@transcript ||= open_transcript).print text
+      end
+
+      def open_transcript
+        state_dir = File.join(ENV.fetch("XDG_STATE_HOME", File.expand_path("~/.local/state")), "elelem", "sessions")
+        FileUtils.mkdir_p(state_dir, mode: 0o700)
+        File.chmod(0o700, state_dir)
+        session_id = "#{Time.now.utc.strftime("%Y%m%dT%H%M%SZ")}-#{Process.pid}"
+        path = File.join(state_dir, "#{session_id}.transcript")
+        File.open(path, "a", 0o600).tap { |f| f.sync = true } # rubocop:disable Style/FileOpen
+      end
+    end
+  end
+end

data/lib/elelem/builtins.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Builtins
+    def self.sh(cmd, args: [], cwd: Dir.pwd, env: {}, timeout: nil)
+      output = StringIO.new
+      options = { chdir: cwd }
+      options[:pgroup] = true if timeout
+
+      Open3.popen2e(env, cmd, *args, **options) do |stdin, out, wait_thr|
+        stdin.close
+        timed_out = false
+        watchdog = timeout && Thread.new do
+          sleep(timeout)
+          timed_out = true
+          terminate(wait_thr.pid)
+        end
+
+        out.each_line do |line|
+          line = line.force_encoding(Encoding::UTF_8).scrub
+          yield line if block_given?
+          output.write(line)
+        end
+        timed_out ? watchdog&.join : watchdog&.kill
+
+        status = wait_thr.value
+        note = timed_out ? "\n[command timed out after #{timeout}s]" : ""
+        { exit_status: status.exitstatus || (timed_out ? 124 : 1), content: truncate(output.string) + note }
+      rescue Interrupt
+        # In its own process group the command never sees Ctrl-C, so stop it here.
+        terminate(wait_thr.pid) if timeout
+        raise
+      end
+    end
+
+    def self.truncate(content, limit: 10_000)
+      return content if content.length <= limit
+
+      half = limit / 2
+      elided = content.length - limit
+      "#{content[0, half]}\n[#{elided} characters elided]\n#{content[-half, half]}"
+    end
+
+    def self.terminate(pid)
+      Process.kill("TERM", -pid)
+      sleep 0.5
+      Process.kill("KILL", -pid)
+    rescue Errno::ESRCH
+      nil
+    end
+  end
+end

data/lib/elelem/cli.rb

@@ -7,12 +7,12 @@ require "reline"
 
 module Elelem
   class CLI
-    COMMANDS = %w[chat ask files help].freeze
-    USAGE = <<~TEXT
+    COMMANDS = %w[chat ask help].freeze
+    USAGE = <<~TEXT.freeze
+      Usage: #{File.basename($PROGRAM_NAME)} [command] [options] [args]
       \nCommands:
         chat              Interactive REPL (default)
         ask <prompt>      One-shot query (reads stdin if piped)
-        files             Output files as XML (no options)
         help              Show this help
       \nOptions:
     TEXT
@@ -20,97 +20,52 @@ module Elelem
 
     def initialize(args, provider: "stub")
       @provider = provider
-      @args = parse(args)
+      @provider_options = {}
+      @parser = OptionParser.new(USAGE) { |o| describe_options(o) }
+      @args = @parser.parse!(args)
     end
 
     def run
       command = @args.shift || "chat"
-      abort "Unknown command: #{command}" unless COMMANDS.include?(command)
-      send(command)
+      COMMANDS.include?(command) ? send(command) : abort("Unknown command: #{command}")
+    rescue StandardError, ScriptError => e
+      Elelem.logger.debug("cli: #{e.message}\n#{e.backtrace.join("\n")}")
+      abort "elelem: #{e.message}"
     end
 
     private
 
-    def parse(args)
-      @parser = OptionParser.new { |o| describe_options(o) }
-      @parser.parse!(args)
-    end
-
     def describe_options(parser)
-      describe_usage(parser)
       parser.on("-p", "--provider NAME", "Provider to use (default: #{@provider})") { |p| @provider = p }
-      parser.on("-h", "--help", "Show this help") { print_help_and_exit(parser) }
-    end
-
-    def print_help_and_exit(parser)
-      puts parser
-      exit
-    end
-
-    def describe_usage(parser)
-      parser.banner = "Usage: #{File.basename($PROGRAM_NAME)} [command] [options] [args]"
-      parser.separator USAGE
+      parser.on("--model NAME", "Model to use, passed to the provider") { |m| @provider_options[:model] = m }
+      parser.on("--system-prompt TEXT", "Role text prepended to the system prompt") { |s| @system_prompt = s }
+      parser.on("-h", "--help", "Show this help") { puts(parser) || exit }
     end
 
-    def help
-      puts @parser
-    end
+    def help = puts(@parser)
 
     def chat
-      Elelem.start(provider: @provider)
-    rescue StandardError, ScriptError => e
-      warn_and_abort(e)
+      Elelem.start(provider: @provider, provider_options: @provider_options, system_prompt: @system_prompt)
     end
 
+    # When stdout is piped, progress goes to stderr and only the reply to stdout.
     def ask
-      abort "Usage: elelem-chat ask <prompt>" if @args.empty?
-
-      reply = Elelem.ask(prompt_for_ask, provider: @provider, output: output_for_ask)
-      print_reply(reply, piped: piped?)
-    rescue StandardError, ScriptError => e
-      warn_and_abort(e)
-    end
+      abort "Usage: elelem ask <prompt>" if @args.empty?
 
-    def piped?
-      !$stdout.tty?
-    end
-
-    def output_for_ask
-      Elelem::Output.new(stream: piped? ? $stderr : $stdout)
+      piped = !$stdout.tty?
+      reply = Elelem.ask(prompt_for_ask, provider: @provider, output: Output.new(stream: piped ? $stderr : $stdout),
+                                         provider_options: @provider_options, system_prompt: @system_prompt)
+      print_reply(reply, piped: piped)
     end
 
     def prompt_for_ask
       prompt = @args.join(" ")
-      $stdin.stat.pipe? ? "#{prompt}\n\n```\n#{$stdin.read}\n```" : prompt
+      $stdin.stat.then { |s| s.pipe? || s.file? } ? "#{prompt}\n\n```\n#{$stdin.read}\n```" : prompt
     end
 
     def print_reply(reply, piped:)
       abort "elelem: no reply" if reply.to_s.strip.empty?
-      Elelem::Output.new.say(reply, as: :markdown) if piped
-    end
-
-    def warn_and_abort(error)
-      Elelem.logger.warn("cli: #{error.message}\n#{error.backtrace.join("\n")}")
-      abort "elelem: #{error.message}"
-    end
-
-    def files
-      puts "<documents>"
-      candidate_files.each_with_index { |line, i| print_document(line, i) }
-      puts "</documents>"
-    end
-
-    def candidate_files
-      $stdin.stat.pipe? ? $stdin.readlines : `git ls-files`.lines
-    end
-
-    def print_document(line, index)
-      path = line.strip
-      return if path.empty? || !File.file?(path)
-
-      content = File.read(path)
-      puts %(<document index="#{index + 1}"><source>#{path}</source>) +
-           %(<document_content><![CDATA[#{content}]]></document_content></document>)
+      $stdout.puts(reply) if piped
     end
   end
 end

data/lib/elelem/commands.rb

@@ -4,6 +4,8 @@ module Elelem
   class Commands
     include Enumerable
 
+    Command = Struct.new(:description, :completions, :handler)
+
     def initialize(registry = {})
       @registry = registry
     end
@@ -13,22 +15,21 @@ module Elelem
     end
 
     def register(name, description: "", completions: nil, &handler)
-      @registry[name] = SlashCommand.new(name, description, completions, &handler)
+      @registry[name] = Command.new(description, completions, handler)
     end
 
+    # completions is a list, or a lambda that returns one.
     def completions_for(name, partial = "")
-      cmd = command_for(name)
-      return [] unless cmd&.completions
-
-      options = cmd.completions.respond_to?(:call) ? cmd.completions.call : cmd.completions
+      options = @registry[name]&.completions || []
+      options = options.call if options.respond_to?(:call)
       options.select { |o| o.start_with?(partial) }
     end
 
     def run(name, args = nil)
-      command = command_for(name)
+      command = @registry[name]
       return false unless command
 
-      command.call(args)
+      command.handler.call(args)
       true
     end
 
@@ -39,11 +40,5 @@ module Elelem
     def each
       @registry.each { |name, command| yield "/#{name}", command.description }
     end
-
-    private
-
-    def command_for(name)
-      @registry[name]
-    end
   end
 end

data/lib/elelem/conversation.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 module Elelem
+  # The messages of a session, behind the system prompt they are sent with.
   class Conversation
     ROLES = %w[user assistant tool].freeze
 
-    def initialize
+    def initialize(template: nil, system_prompt: nil)
       @messages = []
+      @template = SystemPrompt.new(template)
+      @system_prompt = system_prompt
     end
 
     def add(role:, content:, **extra)
@@ -15,12 +18,13 @@ module Elelem
     end
 
     def last = @messages.last
-    def length = @messages.length
     def clear! = @messages.clear
 
-    def to_a(system_prompt: nil)
-      base = system_prompt ? [{ role: "system", content: system_prompt }] : []
-      base + @messages
+    # The system prompt, the messages, then extra: the tool calls of a turn.
+    def to_a(extra = [])
+      # The role text is the model's own words, so it is never run as ERB.
+      system = [@system_prompt, @template.render].compact.join("\n\n")
+      [{ role: "system", content: system }, *@messages, *extra]
     end
   end
 end

data/lib/elelem/input.rb

@@ -4,14 +4,18 @@ require "reline"
 
 module Elelem
   class Input
-    def initialize(commands: [])
+    def initialize(commands: Commands.new)
       @commands = commands
       Reline.autocompletion = true
       Reline.completion_proc = ->(target, preposing) { complete(target, preposing) }
     end
 
     def ask(prompt)
-      Reline.readline(prompt, true)&.strip
+      Reline.readline(prompt, false)&.strip
+    end
+
+    def remember(line)
+      Reline::HISTORY << line
     end
 
     def interactive?
@@ -22,25 +26,14 @@ module Elelem
 
     def complete(target, preposing)
       line = "#{preposing}#{target}"
-      return command_names.select { |c| c.start_with?(line) } if line.start_with?("/") && !preposing.include?(" ")
-      return complete_command_args_for(preposing, target) if preposing.start_with?("/") && preposing.include?(" ")
+      return @commands.names.select { |c| c.start_with?(line) } if line.start_with?("/") && !preposing.include?(" ")
+      return complete_command_args(preposing, target) if preposing.start_with?("/") && preposing.include?(" ")
 
       complete_files(target)
     end
 
-    def complete_command_args_for(preposing, target)
-      cmd_name = preposing.delete_prefix("/").split(" ", 2).first
-      complete_command_args(cmd_name, target)
-    end
-
-    def command_names
-      @commands.respond_to?(:names) ? @commands.names : @commands
-    end
-
-    def complete_command_args(cmd_name, partial)
-      return [] unless @commands.respond_to?(:completions_for)
-
-      @commands.completions_for(cmd_name, partial)
+    def complete_command_args(preposing, target)
+      @commands.completions_for(preposing.delete_prefix("/").split(" ", 2).first, target)
     end
 
     def complete_files(target)

data/lib/elelem/null_output.rb

@@ -2,6 +2,8 @@
 
 module Elelem
   class NullOutput < Output
-    def say(*, **) = nil
+    private
+
+    def write(_text) = nil
   end
 end

data/lib/elelem/plugins/builtins.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:builtins) do |agent|
+    agent.commands.register("exit", description: "Exit elelem") { exit(0) }
+
+    agent.commands.register("clear", description: "Clear conversation history") do
+      agent.conversation.clear!
+      agent.output.say "  -> context cleared"
+    end
+
+    agent.commands.register("help", description: "Show available commands") do
+      agent.output.say agent.commands.map { |name, description| "#{name.ljust(12)} #{description}" }.join("\n")
+    end
+  end
+end

data/lib/elelem/plugins/context.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:context) do |agent|
+    agent.commands.register("context", description: "Show conversation context") do |args|
+      messages = agent.context
+
+      case args
+      when nil, ""
+        messages.each_with_index do |msg, i|
+          role = msg[:role]
+          preview = msg[:content].to_s.lines.first&.strip&.slice(0, 60) || ""
+          preview += "..." if msg[:content].to_s.length > 60
+          agent.output.say "  #{i + 1}. #{role}: #{preview}"
+        end
+      when "json"
+        agent.output.say JSON.pretty_generate(messages)
+      when /^\d+$/
+        index = args.to_i - 1
+        if index >= 0 && index < messages.length
+          content = messages[index][:content].to_s
+          agent.output.say(content, as: :markdown)
+        else
+          agent.output.say "  Invalid index: #{args}"
+        end
+      else
+        agent.output.say "  Usage: /context [json|<number>]"
+      end
+    end
+  end
+end

data/lib/elelem/plugins/execute.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:execute) do |agent|
+    agent.toolbox.add("execute",
+                      description: "Run shell command (supports pipes and redirections)",
+                      params: { command: { type: "string" } },
+                      required: ["command"],
+                      aliases: ["bash", "sh", "exec", "execute<|channel|>"]) do |a|
+      # The timeout kills the whole process group, so `npm start &` cannot hang the session.
+      value = ENV.fetch("ELELEM_CMD_TIMEOUT", "")
+      timeout = value.empty? ? 300 : Integer(value)
+      timeout = nil if timeout.zero?
+      result = Elelem::Builtins.sh("bash", args: ["-c", a["command"]], timeout: timeout) { |x| agent.output.print(x) }
+      result.merge(ok: result[:exit_status].zero?)
+    end
+
+    agent.toolbox.after("execute") do |args, result|
+      next if result[:exit_status].zero?
+
+      agent.output.doing("execute", args, state: "x")
+    end
+  end
+end