elelem 0.11.0 → 0.13.0

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

data/lib/elelem/plugins/provider.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:provider) do |session|
+    session.commands.register("provider", description: "Switch provider: /provider NAME [MODEL]", completions: lambda {
+      Elelem::Config.names
+    }) do |args|
+      name, model = args.to_s.split
+      next session.output.say("  -> available: #{Elelem::Config.names.join(", ")}") if name.nil?
+
+      # --model carries over only to the provider it was given for.
+      options = if model then { model: }
+                elsif name == session.provider_name then session.provider_options
+                else {}
+                end
+      session.provider = Elelem::Config.build_provider(name, **options)
+      session.provider_name = name
+      session.provider_options = options
+      session.output.say "  -> switched to #{name}"
+    end
+  end
+end

data/lib/elelem/plugins/read.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:read) do |agent|
+    agent.toolbox.add("read",
+                      description: "Read file",
+                      params: { path: { type: "string" } },
+                      required: ["path"],
+                      aliases: ["open"]) do |a|
+      path = Pathname.new(a["path"]).expand_path
+      next { error: "not found" } unless path.exist?
+
+      content = path.binread
+      next { error: "binary file (#{content.bytesize} bytes)" } if content.include?("\0")
+
+      content = content.force_encoding(Encoding::UTF_8).scrub
+
+      { content: Elelem::Builtins.truncate(content), path: a["path"] }
+    end
+
+    agent.toolbox.after("read") do |_, result|
+      if result[:error]
+        agent.output.say "  ! #{result[:error]}"
+      else
+        agent.output.display_file(result[:path], fallback: result[:content])
+      end
+    end
+  end
+end

data/lib/elelem/plugins/reload.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:reload) do |agent|
+    agent.commands.register("reload", description: "Reload plugin code from disk") do
+      Elelem::Config.reload(agent)
+    end
+  end
+end

data/lib/elelem/plugins/terminal.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# The default output. A gem that registers its own output first keeps it.
+Elelem.configure do |config|
+  config.output { Elelem::Builtins::Terminal.new } unless config.factories.key?(:output)
+end

data/lib/elelem/plugins/tools.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:tools) do |agent|
+    describe = lambda do |tool|
+      parameters = tool.to_h.dig(:function, :parameters)
+      lines = ["## #{tool.name}", "", tool.description, "", "### Parameters", ""]
+      parameters[:properties].each do |param, spec|
+        req = parameters[:required].include?(param.to_s) ? ", required" : ""
+        desc = spec[:description] ? " - #{spec[:description]}" : ""
+        lines << "- `#{param}` (#{spec[:type]}#{req})#{desc}"
+      end
+      lines << "" << "*aliases: #{tool.aliases.join(", ")}*" if tool.aliases.any?
+      lines.join("\n")
+    end
+
+    completions = -> { agent.toolbox.tools.keys }
+    agent.commands.register("tools", description: "List available tools", completions: completions) do |arg|
+      tool = agent.toolbox.tools[arg] if arg && !arg.empty?
+      if tool
+        agent.output.say describe.call(tool), as: :markdown
+      elsif arg && !arg.empty?
+        agent.output.say "Unknown tool: #{arg}"
+      else
+        # values copies the list, so a plugin adding tools from a thread cannot break this loop.
+        rows = agent.toolbox.tools.values.map { |t| "| #{t.name} | #{t.description.lines.first.chomp} |" }
+        agent.output.say "| Tool | Description |\n|------|-------------|\n#{rows.join("\n")}", as: :markdown
+      end
+    end
+  end
+end

data/lib/elelem/plugins/write.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:write) do |agent|
+    agent.toolbox.add("write",
+                      description: "Write file",
+                      params: { path: { type: "string" }, content: { type: "string" } },
+                      required: %w[path content],
+                      aliases: ["write<|channel|>"]) do |a|
+      path = Pathname.new(a["path"]).expand_path
+      FileUtils.mkdir_p(path.dirname)
+      { bytes: path.write(a["content"]), path: a["path"] }
+    end
+
+    agent.toolbox.before("write") do |args|
+      path = Pathname.new(args["path"]).expand_path
+      next unless path.exist? && agent.input.interactive?
+
+      Tempfile.create(["elelem", File.extname(path)]) do |t|
+        t.write(args["content"])
+        t.flush
+        diff, = Open3.capture2("diff", "--color=always", "-u", path.to_s, t.path)
+        agent.output.print(diff)
+      end
+    rescue Errno::ENOENT
+      nil # no diff installed
+    end
+
+    agent.toolbox.after("write") do |_, result|
+      agent.output.display_file(result[:path], fallback: "  -> #{result[:path]}")
+      # The model sees the checks in the write's own result.
+      if agent.toolbox.tools.key?("verify")
+        result[:verify] = agent.toolbox.run("verify", { "path" => result[:path] }).to_h
+      end
+    end
+  end
+end

data/lib/elelem/plugins.rb

@@ -3,6 +3,7 @@
 module Elelem
   class Plugins
     LOAD_PATHS = [
+      File.expand_path("plugins", __dir__),
       "~/.agents/plugins",
       ".agents/plugins"
     ].freeze
@@ -15,18 +16,26 @@ module Elelem
     def load!(force: false)
       return if @loaded && !force
 
-      @load_paths.each do |path|
-        dir = File.expand_path(path)
-        next unless File.directory?(dir)
+      dirs.each { |dir| load_dir(dir) }
+      @loaded = true
+    end
 
-        Dir["#{dir}/*.rb"].sort.each do |file|
-          load(file)
-        rescue => e
-          warn "elelem: failed to load plugin #{file}: #{e.message}"
-        end
-      end
+    def dirs
+      @load_paths.map { |path| File.expand_path(path) }
+    end
 
-      @loaded = true
+    private
+
+    def load_dir(dir)
+      return unless File.directory?(dir)
+
+      Dir["#{dir}/*.rb"].each { |file| load_plugin(file) }
+    end
+
+    def load_plugin(file)
+      load(file)
+    rescue StandardError, ScriptError => e
+      $stderr.puts "elelem: failed to load plugin #{file}: #{e.message}"
     end
   end
 end

data/lib/elelem/registration.rb

@@ -30,8 +30,13 @@ module Elelem
       self
     end
 
-    def clear_setups!
-      @setups.clear
+    # Drops setups defined in files under dirs. Gem setups are kept, since
+    # require will not run them again.
+    def clear_setups_from!(dirs)
+      @setups.reject! do |_, block|
+        file = block.source_location&.first.to_s
+        dirs.any? { |dir| file.start_with?("#{dir}/") }
+      end
     end
   end
 end

data/lib/elelem/registry.rb

@@ -12,58 +12,62 @@ module Elelem
       self
     end
 
-    def build_provider(name)
+    def build_provider(name, **)
       @plugins.load!
-      @registration.providers.fetch(name.to_s) { require_gem(name) }.call
+      @registration.providers.fetch(name.to_s) { require_gem(name) }.call(**)
     end
 
-    def apply(agent)
+    def apply(session)
       @plugins.load!
-      @registration.setups.each_value { |block| block.call(agent) }
+      @registration.setups.each_value { |block| block.call(session) }
     end
 
-    def reload(agent)
-      @registration.clear_setups!
-      agent.toolbox.clear!
-      agent.commands.clear!
+    def reload(session)
+      @registration.clear_setups_from!(@plugins.dirs)
+      session.toolbox.clear!
+      session.commands.clear!
       @plugins.load!(force: true)
-      apply(agent)
+      apply(session)
     end
 
     def names
       @registration.providers.keys
     end
 
-    def build_agent(provider, toolbox: Toolbox.new, input: nil, output: nil)
+    def build_session(provider, toolbox: Toolbox.new, input: nil, output: nil, provider_options: {},
+                      template: nil, system_prompt: nil)
       commands = Commands.new
-      agent = Agent.new(
-        build_provider(provider),
-        toolbox: toolbox,
-        commands: commands,
-        input: input || build_input(commands: commands),
-        output: output || build_output,
-      )
-      apply(agent)
-      agent
+      agent = Agent.new(build_provider(provider, **provider_options), toolbox: toolbox, output: output || build_output,
+                                                                      template: template, system_prompt: system_prompt)
+      session = Session.new(agent, input: input || build_input(commands: commands), commands: commands,
+                                   provider_name: provider, provider_options: provider_options)
+      apply(session)
+      session
     end
 
     private
 
-    def build_input(**opts)
+    def build_input(**)
       @plugins.load!
-      (@registration.factories[:input] || ->(**o) { Input.new(**o) }).call(**opts)
+      (@registration.factories[:input] || ->(**o) { Input.new(**o) }).call(**)
     end
 
-    def build_output(**opts)
+    def build_output(**)
       @plugins.load!
-      (@registration.factories[:output] || ->(**o) { Output.new(**o) }).call(**opts)
+      (@registration.factories[:output] || ->(**o) { Output.new(**o) }).call(**)
     end
 
     def require_gem(name)
       require "elelem/#{name}"
-      @registration.providers.fetch(name.to_s) { raise "elelem-#{name} did not register a provider named #{name.inspect}" }
-    rescue LoadError
+      @registration.providers.fetch(name.to_s) { unregistered_provider(name) }
+    rescue LoadError => e
+      raise unless e.path == "elelem/#{name}"
+
       raise "unknown provider: #{name.inspect}. Available: #{names.join(", ")}. Run: gem install elelem-#{name}"
     end
+
+    def unregistered_provider(name)
+      raise "elelem-#{name} did not register a provider named #{name.inspect}"
+    end
   end
 end

data/lib/elelem/repl.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Elelem
+  class Repl
+    def initialize(session)
+      @session = session
+    end
+
+    def run
+      @session.output.say "elelem v#{VERSION}"
+      while (line = @session.input.ask("> "))
+        dispatch_line(line) unless line.empty?
+      end
+    end
+
+    private
+
+    # Only lines typed at the prompt go in history, not answers to a tool.
+    # A line is a command only when its first word names one, so a path such
+    # as /etc/hosts reaches the model. One failed turn does not end the session.
+    def dispatch_line(line)
+      @session.input.remember(line) if @session.input.respond_to?(:remember)
+      command(line) || @session.turn(line)
+    rescue StandardError, ScriptError => e
+      Elelem.logger.debug("repl: #{e.message}")
+      @session.output.say(e.message, as: :error)
+    end
+
+    def command(line)
+      name, args = line.delete_prefix("/").split(" ", 2)
+      line.start_with?("/") && @session.commands.run(name, args)
+    end
+  end
+end

data/lib/elelem/result.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
-require "forwardable"
-
 module Elelem
   class Result
     extend Forwardable
+
     def_delegators :@payload, :[], :each, :to_json, :to_h, :key?, :merge
 
     def self.success(payload)
@@ -20,7 +19,5 @@ module Elelem
     end
 
     def ok? = !!@payload[:ok]
-    def error? = !!@payload[:error]
-    def error = @payload[:error]
   end
 end

data/lib/elelem/session.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Elelem
+  class Session
+    extend Forwardable
+
+    attr_reader :agent, :input, :commands
+    # The provider the session was built with, and its options (such as --model).
+    attr_accessor :provider_name, :provider_options
+
+    def_delegators :@agent, :provider, :provider=, :toolbox, :output, :conversation, :context, :turn
+
+    def initialize(agent, input: NullInput.new, commands: Commands.new, provider_name: nil, provider_options: {})
+      @agent = agent
+      @input = input
+      @commands = commands
+      @provider_name = provider_name&.to_s
+      @provider_options = provider_options
+    end
+  end
+end

data/lib/elelem/stub_provider.rb

@@ -1,15 +1,76 @@
 # frozen_string_literal: true
 
 module Elelem
+  # No model. Understands a tool name and its arguments, and the few plain
+  # requests the docs show. Reads only the first line, so piped text never
+  # becomes arguments.
   class StubProvider
-    def fetch(messages, tools = [], &block)
-      block.call(type: "thinking", text: "considering the request")
-      return block.call(type: "saying", text: "done.") if messages.last[:role] == "tool"
+    REQUESTS = [
+      [/\Ashow me (\S+?)[.?!]?\z/i, "read", ->(m) { { "path" => m[1] } }],
+      [%r{\Acreate (\S*[./]\S*) with (.+)\z}i, "write", ->(m) { { "path" => m[1], "content" => m[2] } }],
+      [/\Awhat files are here\??\z/i, "execute", ->(_) { { "command" => "ls" } }],
+      [/\Arun (?:the )?tests?\z/i, "execute",
+       ->(_) { { "command" => File.executable?("bin/test") ? "bin/test" : "rake" } }],
+      [/\A(?:run|execute) `?(.+?)`?\z/i, "execute", ->(m) { { "command" => m[1] } }]
+    ].freeze
 
-      block.call(type: "saying", text: "let me check.")
-      return unless (tool = tools.first)
+    HELP = <<~TEXT
+      I need a model to understand that. Without one, type a tool and its
+      arguments (/tools lists them), or: show me README.md, create notes.txt
+      with hello, what files are here, run the tests.
+      For a model: gem install elelem-llama, then elelem -p llama
+    TEXT
 
-      block.call(type: "doing", id: "stub-1", name: tool[:function][:name], arguments: {})
+    def fetch(messages, tools = [], &)
+      return yield(type: "saying", text: summary(messages)) if messages.last[:role] == "tool"
+
+      name, args = understand(messages.last[:content], tools)
+      name ? act(name, args, messages.length, &) : yield(type: "saying", text: HELP)
+    end
+
+    private
+
+    def act(name, args, turn)
+      yield(type: "thinking", text: "I'll call #{name}.")
+      yield(type: "doing", id: "stub-#{turn}", name: name, arguments: args)
+    end
+
+    def understand(content, tools)
+      text = content.to_s.lines.first.to_s.strip
+      request(text, tools.map { |t| t.dig(:function, :name) }) || direct(text, tools)
+    end
+
+    def request(text, names)
+      REQUESTS.each do |pattern, name, build|
+        match = pattern.match(text)
+        return [name, build.call(match)] if match && names.include?(name)
+      end
+      nil
+    end
+
+    def direct(text, tools)
+      name, rest = text.split(/\s+/, 2)
+      tool = tools.find { |t| t.dig(:function, :name) == name }
+      args = arguments(tool, rest.to_s) if tool
+      [name, args] if args && file_like?(name, args)
+    end
+
+    def arguments(tool, rest)
+      required = tool.dig(:function, :parameters, :required) || []
+      required.zip(rest.split(/\s+/, required.size)).to_h.compact.transform_keys(&:to_s)
+    end
+
+    # A model would not write to "a" when asked to "write a commit message".
+    def file_like?(name, args)
+      name != "write" || args["path"].to_s.match?(%r{[./]})
+    end
+
+    def summary(messages)
+      name = messages.rfind { |m| m[:tool_calls] }&.dig(:tool_calls, 0, :name)
+      result = JSON.parse(messages.last[:content].to_s).except("ok")
+      return "#{name} failed: #{result["error"]}." if result["error"]
+
+      result.empty? ? "#{name} is done." : result.map { |k, v| "#{k}: #{v}" }.join("\n")
     end
   end
 end

data/lib/elelem/system_prompt.rb

@@ -3,8 +3,9 @@
 module Elelem
   class SystemPrompt
     DEFAULT = File.read(File.expand_path("prompts/default.erb", __dir__)).freeze
+    USER_AGENTS_MD = Pathname.new(Dir.home).join(".agents/AGENTS.md").freeze
 
-    attr_accessor :template
+    attr_reader :template
 
     def initialize(template = nil)
       @template = template || DEFAULT
@@ -17,6 +18,14 @@ module Elelem
     private
 
     def agents_md
+      [global_agents_md, project_agents_md].compact.then { |parts| parts.empty? ? nil : parts.join("\n\n") }
+    end
+
+    def global_agents_md
+      USER_AGENTS_MD.read if USER_AGENTS_MD.exist?
+    end
+
+    def project_agents_md
       Pathname.pwd.ascend.each do |dir|
         file = dir / "AGENTS.md"
         return file.read if file.exist?

data/lib/elelem/tool.rb

@@ -2,39 +2,20 @@
 
 module Elelem
   class Tool
-    attr_reader :name, :description, :params, :required, :aliases
+    attr_reader :name, :description, :aliases
 
-    def initialize(name, description:, params: {}, required: [], aliases: [], &fn)
+    # params and required are JSON Schema; every call is checked against them.
+    def initialize(name, description:, params: {}, required: [], aliases: [], &handler)
       @name = name
       @description = description
-      @params = params.freeze
-      @required = required.freeze
       @aliases = aliases.freeze
-      @fn = fn
-      @schema_hash = { type: "object", properties: @params, required: @required }.freeze
-      @schema = JSONSchemer.schema(@schema_hash)
-    end
-
-    def call(args)
-      @fn.call(args)
-    end
-
-    def validate(args)
-      @schema.validate(args || {}).map do |error|
-        error["error"]
-      end
-    end
-
-    def to_h
-      {
-        type: "function",
-        function: {
-          name: name,
-          description: description,
-          parameters: @schema_hash
-        }
-      }
+      @handler = handler
+      @schema = { type: "object", properties: params.freeze, required: required.freeze }.freeze
     end
 
+    def call(args) = @handler.call(args)
+    def validate(args) = (@validator ||= JSONSchemer.schema(@schema)).validate(args || {}).map { |e| e["error"] }
+    def inspect = "#<#{self.class} #{name}>"
+    def to_h = { type: "function", function: { name: name, description: description, parameters: @schema } }
   end
 end