elelem-builtins 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e9add550f4e090bdfedad12f0ace36276ab00db2f2c1c1af51d0dd2c2dfaef8c
+  data.tar.gz: 3e1dc2c8c59c56b273161578ac5628fdfac317f2a0cbca3566ea878255d4610a
+SHA512:
+  metadata.gz: '08a66e554544c36454bdc6f99e0987ddbda1072a4216acd9b34a3b9201cd73c204a40504e6e0ceef8c37bafca13086530ac5213116954b5268b334f362d376f2'
+  data.tar.gz: 8cae217a61971f7f9b572ee88e58969b2b1cdfd2b6020dd03f0192406059350556649498823be467f874cf5535be2579f393d01d23151f714c1ae645297884e1

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 mo khan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec]

data/lib/elelem/builtins/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/builtins/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/builtins/execute.rb

@@ -0,0 +1,20 @@
+# 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|
+      Elelem::Builtins.sh("bash", args: ["-c", a["command"]], timeout: Elelem::Builtins.command_timeout) { |x| agent.output.print(x) }
+    end
+
+    agent.toolbox.after("execute") do |args, result|
+      next if result[:exit_status] == 0
+
+      agent.output.doing("execute", args, state: "x")
+    end
+  end
+end

data/lib/elelem/builtins/provider.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:provider) do |agent|
+    agent.commands.register("provider", description: "Switch provider", completions: -> { Elelem::Config.names }) do |name|
+      if name.nil? || name.empty?
+        agent.output.say "  → available: #{Elelem::Config.names.join(", ")}"
+      else
+        agent.client = Elelem::Config.build_client(name)
+        agent.output.say "  → switched to #{name}"
+      end
+    end
+  end
+end

data/lib/elelem/builtins/read.rb

@@ -0,0 +1,23 @@
+# 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
+      path.exist? ? { content: path.read, path: a["path"] } : { error: "not found" }
+    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/builtins/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/builtins/terminal.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Builtins
+    class Terminal < Elelem::Terminal
+      def display_file(path, fallback: nil)
+        system("bat", "--paging=never", path) || say(fallback || path)
+      end
+
+      private
+
+      def render(text, as)
+        return super unless as == :markdown
+
+        gap
+        width = @stream.winsize[1] rescue 80
+        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 write(text)
+        super
+        (@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)
+        session_id = "#{Time.now.utc.strftime("%Y%m%dT%H%M%SZ")}-#{Process.pid}"
+        File.open(File.join(state_dir, "#{session_id}.transcript"), "a").tap { |f| f.sync = true }
+      end
+    end
+  end
+end
+
+Elelem.configure { |config| config.output { Elelem::Builtins::Terminal.new } }

data/lib/elelem/builtins/tools.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Builtins
+    module ToolMarkdown
+      def self.summary(tool)
+        "| #{tool.name} | #{tool.description.lines.first.chomp} |"
+      end
+
+      def self.to_markdown(tool)
+        lines = ["## #{tool.name}", "", tool.description, "", "### Parameters", ""]
+        tool.params.each do |param, spec|
+          req = tool.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
+    end
+  end
+end
+
+Elelem.configure do |config|
+  config.setup(:tools) do |agent|
+    completions = -> { agent.toolbox.tools.keys }
+
+    agent.commands.register("tools", description: "List available tools", completions: completions) do |arg|
+      if arg && !arg.empty?
+        tool = agent.toolbox.tools[arg]
+        unless tool
+          agent.output.say "Unknown tool: #{arg}"
+          next
+        end
+
+        agent.output.say Elelem::Builtins::ToolMarkdown.to_markdown(tool), as: :markdown
+      else
+        rows = agent.toolbox.tools.each_value.map { |tool| Elelem::Builtins::ToolMarkdown.summary(tool) }
+
+        md = String.new("| Tool | Description |\n")
+        md << "|------|-------------|\n"
+        md << rows.join("\n")
+
+        agent.output.say md, as: :markdown
+      end
+    end
+  end
+end

data/lib/elelem/builtins/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Builtins
+    VERSION = "0.2.0"
+  end
+end

data/lib/elelem/builtins/write.rb

@@ -0,0 +1,36 @@
+# 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: ["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? && $stdin.tty?
+
+      Tempfile.create(["elelem", File.extname(path)]) do |t|
+        t.write(args["content"])
+        t.flush
+        system("diff", "--color=always", "-u", path.to_s, t.path)
+      end
+    end
+
+    agent.toolbox.after("write") do |_, result|
+      if result[:error]
+        agent.output.say "  ! #{result[:error]}"
+      else
+        agent.output.display_file(result[:path], fallback: "  -> #{result[:path]}")
+        agent.toolbox.run("verify", { "path" => result[:path] }) if agent.toolbox.tools.key?("verify")
+      end
+    end
+  end
+end

data/lib/elelem/builtins.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "elelem"
+require "fileutils"
+require "json"
+require "open3"
+require "pathname"
+require "stringio"
+require "tempfile"
+
+require_relative "builtins/version"
+
+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|
+          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 }
+      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
+
+    def self.command_timeout
+      value = ENV["ELELEM_CMD_TIMEOUT"]
+      value && !value.empty? ? Integer(value) : nil
+    end
+  end
+end
+
+require_relative "builtins/provider"
+require_relative "builtins/reload"
+require_relative "builtins/builtins"
+require_relative "builtins/context"
+require_relative "builtins/tools"
+require_relative "builtins/read"
+require_relative "builtins/write"
+require_relative "builtins/execute"
+require_relative "builtins/terminal"

data/spec/elelem/builtins/tool_markdown_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+RSpec.describe Elelem::Builtins::ToolMarkdown do
+  subject(:tool) do
+    Elelem::Tool.new("greet",
+      description: "Greets someone.\nMore detail.",
+      params: { name: { type: "string", description: "who to greet" } },
+      required: ["name"],
+      aliases: ["hi"]
+    ) { |args| { greeting: "hi #{args["name"]}" } }
+  end
+
+  describe ".summary" do
+    it "renders a single table row with the first description line" do
+      expect(described_class.summary(tool)).to eq("| greet | Greets someone. |")
+    end
+  end
+
+  describe ".to_markdown" do
+    it "renders name, description, params, and aliases" do
+      markdown = described_class.to_markdown(tool)
+
+      expect(markdown).to include("## greet")
+      expect(markdown).to include("Greets someone.\nMore detail.")
+      expect(markdown).to include("- `name` (string, required) - who to greet")
+      expect(markdown).to include("*aliases: hi*")
+    end
+
+    it "omits the aliases line when there are none" do
+      plain_tool = Elelem::Tool.new("greet", description: "Greets someone.") { }
+
+      expect(described_class.to_markdown(plain_tool)).not_to include("aliases:")
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "../lib/elelem/builtins"
+
+RSpec.configure do |config|
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: elelem-builtins
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- mo khan
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: elelem
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: fileutils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: open3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: stringio
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: tempfile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: Bundles the execute, read, write, tools, context, provider, reload, and
+  builtins plugins that make a freshly-installed elelem agent useful.
+email:
+- mo@mokhan.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE.txt
+- Rakefile
+- lib/elelem/builtins.rb
+- lib/elelem/builtins/builtins.rb
+- lib/elelem/builtins/context.rb
+- lib/elelem/builtins/execute.rb
+- lib/elelem/builtins/provider.rb
+- lib/elelem/builtins/read.rb
+- lib/elelem/builtins/reload.rb
+- lib/elelem/builtins/terminal.rb
+- lib/elelem/builtins/tools.rb
+- lib/elelem/builtins/version.rb
+- lib/elelem/builtins/write.rb
+- spec/elelem/builtins/tool_markdown_spec.rb
+- spec/spec_helper.rb
+homepage: https://src.mokhan.ca/elelem/builtins
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://src.mokhan.ca/elelem/builtins
+  source_code_uri: https://src.mokhan.ca/elelem/builtins
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Default tools and commands for elelem.
+test_files: []