elelem 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e95bbe823f4cf39a8a801bd32240caa47dcc3bdea6ce803f7c744f5f192f74c
-  data.tar.gz: 685b6b52ff14408979bd61a0ea42e87d24602f398392ac845fcc893eceabccae
+  metadata.gz: d4696869850fc38fba45a65a38aca74f8663fe9b8562deb7a987cbc71058221a
+  data.tar.gz: 8ec379df1537243659cfee997c02fde40912be780ace54b14bb0ff181f5fad64
 SHA512:
-  metadata.gz: cc605e03c30962a7f75d0846cde1bfb46d41c73ffbd07ee49f933fe51076ae08df7f9fb86b933d16864fd5aad7de9a29297d3b7da01337a9aa62d80aa9fa5940
-  data.tar.gz: 5d2580db0a5e607c360bb1f691d2eabaec7a37af7ca4f705950fed4048a567be46077c04e5a289163473f679ec95b76b8b04e5c56d84a3bb4eb42be6cc1b4da6
+  metadata.gz: 52e225e4b206091bcd1838cce432ee2391c648fa4f995a722dfefc2820985bb405e5e3574a972a8e31be260695eb368f3f6f3dcfa32f8cbeeb76b5fab6b1a2f3
+  data.tar.gz: c508bfedce1daf081011046ca77a13872af1bb133d161edfb944d7e4019e92222b15dc9aeb4f98376328e099a62e5ec89f2b67d2f595ed6ea6a58281a0a44589

data/README.md

@@ -1,77 +1,17 @@
 # Elelem
 
-Fast, correct, autonomous – pick two.
+Fast, correct, autonomous - pick two.
 
 ## Purpose
 
-Elelem is a minimal coding agent written in Ruby. It is designed to help
-you write, edit, and manage code and plain-text files from the command line
-by delegating work to an LLM. The agent exposes a simple text-based UI and a
-set of built-in tools that give the LLM access to the local file system.
+Elelem is a minimal coding harness. The agent exposes a simple text-based UI.
 
 ## Design Principles
 
-* Unix philosophy – simple, composable, minimal.
+* Unix philosophy - simple, composable, minimal.
 * Convention over configuration.
 * No defensive checks or complexity beyond what is necessary.
 * Assumes a mature, responsible LLM that behaves like a capable engineer.
-* Optimised for my personal workflow and preferences.
-* Efficient and minimal like *aider* – https://aider.chat/.
-* UX similar to Claude Code – https://docs.claude.com/en/docs/claude-code/overview.
-
-## System Assumptions
-
-* Linux host with Alacritty, tmux, Bash, Vim.
-* Runs inside a Git repository.
-* Git is available and functional.
-
-## Dependencies
-
-Elelem relies on several external tools. Install the ones you need:
-
-| Tool | Purpose | Install |
-|------|---------|---------|
-| [ast-grep](https://ast-grep.github.io/) | Structural search (`sg`) | `brew install ast-grep` / `cargo install ast-grep` |
-| [ctags](https://ctags.io/) | Repo map generation | `brew install universal-ctags` / `apt install universal-ctags` |
-| [fd](https://github.com/sharkdp/fd) | File discovery | `brew install fd` / `apt install fd-find` |
-| [git](https://git-scm.com/) | Version control | `brew install git` / `apt install git` |
-| [glow](https://github.com/charmbracelet/glow) | Markdown rendering | `brew install glow` / `go install github.com/charmbracelet/glow@latest` |
-| [jq](https://jqlang.github.io/jq/) | JSON processing | `brew install jq` / `apt install jq` |
-| [ollama](https://ollama.ai/) | Default LLM provider | https://ollama.ai/download |
-| [ripgrep](https://github.com/BurntSushi/ripgrep) | Text search (`rg`) | `brew install ripgrep` / `apt install ripgrep` |
-
-**Required:** Git, Ollama (or another LLM provider)
-
-**Recommended:** glow, jq, ctags, ripgrep, fd
-
-**Optional:** ast-grep (for structural code search)
-
-## Scope
-
-Only plain-text and source-code files are supported. No binary handling,
-sandboxing, or permission checks are performed - the LLM has full access.
-
-## Configuration
-
-Prefer convention over configuration. Add environment variables only after
-repeated use proves their usefulness.
-
-## UI Expectations
-
-Keyboard-driven, minimal TUI. No mouse support or complex widgets.
-
-## Coding Standards for the LLM
-
-* No extra error handling unless essential.
-* Keep methods short, single-purpose.
-* Descriptive, conventional names.
-* Use Ruby standard library where possible.
-
-## Helpful Links
-
-* https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
-* https://www.anthropic.com/engineering/writing-tools-for-agents
-* https://simonwillison.net/2025/Sep/30/designing-agentic-loops/
 
 ## Installation
 
@@ -89,144 +29,17 @@ Start an interactive chat session:
 elelem chat
 ```
 
-### Options
+## Tools
 
-* `--provider` – LLM provider: `ollama`, `anthropic`, `openai`, or `vertex-ai` (default: `ollama`).
-* `--model` – Override the default model for the selected provider.
+Use the plugin API to add tools.
 
-### Examples
+## Contributing
 
 ```bash
-# Default (Ollama)
-elelem chat
-
-# Anthropic Claude
-ANTHROPIC_API_KEY=sk-... elelem chat --provider anthropic
-
-# OpenAI
-OPENAI_API_KEY=sk-... elelem chat --provider openai
-
-# VertexAI (uses gcloud ADC)
-elelem chat --provider vertex-ai --model claude-sonnet-4@20250514
-```
-
-### Provider Configuration
-
-Each provider reads its configuration from environment variables:
-
-| Provider    | Environment Variables                              |
-|-------------|---------------------------------------------------|
-| ollama      | `OLLAMA_HOST` (default: localhost:11434)          |
-| anthropic   | `ANTHROPIC_API_KEY`                               |
-| openai      | `OPENAI_API_KEY`, `OPENAI_BASE_URL`               |
-| vertex-ai   | `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_REGION`     |
-
-## Features
-
-* **Interactive REPL** – clean, streaming chat.
-* **Toolbox** – file I/O and shell execution.
-* **Streaming Responses** – output appears in real time.
-* **Conversation History** – persists across turns; can be cleared.
-* **Context Dump** – `/context` shows the current conversation state.
-
-## Tools
-
-Built-in tools available to the LLM:
-
-| Tool      | Purpose                    | Parameters                |
-| --------- | -------------------------- | ------------------------- |
-| `read`    | Read file contents         | `path`                    |
-| `write`   | Write file                 | `path`, `content`         |
-| `edit`    | Replace text in file       | `path`, `old`, `new`      |
-| `execute` | Run shell command          | `command`                 |
-| `eval`    | Execute Ruby code          | `ruby`                    |
-| `glob`    | Find files by pattern      | `pattern`, `path`         |
-| `grep`    | Search file contents       | `pattern`, `path`, `glob` |
-| `list`    | List directory             | `path`, `recursive`       |
-| `git`     | Run git command            | `command`, `args`         |
-| `task`    | Delegate to sub-agent      | `prompt`                  |
-| `verify`  | Check syntax and run tests | `path`                    |
-
-Aliases: `bash`, `sh`, `exec` → `execute`; `open` → `read`; `ls` → `list`
-
-## Plugins
-
-Plugins extend elelem with custom tools and commands. They are loaded from:
-- `lib/elelem/plugins/` (built-in)
-- `~/.elelem/plugins/` (user global)
-- `.elelem/plugins/` (project local)
-
-### Writing a Plugin
-
-```ruby
-# ~/.elelem/plugins/hello.rb
-Elelem::Plugins.register(:hello) do |agent|
-  # Add a tool
-  agent.toolbox.add("hello",
-    description: "Say hello",
-    params: { name: { type: "string" } },
-    required: ["name"]
-  ) do |args|
-    { message: "Hello, #{args["name"]}!" }
-  end
-
-  # Add a command
-  agent.commands.register("greet", description: "Greet the user") do
-    agent.terminal.say "Hello!"
-  end
-
-  # Add hooks
-  agent.toolbox.before("execute") { |args| puts "Running: #{args["command"]}" }
-  agent.toolbox.after("execute") { |args, result| puts "Exit: #{result[:exit_status]}" }
-
-  # Global hook (runs for all tools)
-  agent.toolbox.before { |args, tool_name:| puts "Calling #{tool_name}" }
-end
-```
-
-### Plugin API
-
-Plugins receive an `agent` object with access to:
-- `agent.toolbox` - add tools, register hooks
-- `agent.terminal` - output to the user (`say`, `ask`, `markdown`)
-- `agent.commands` - register slash commands
-- `agent.conversation` - access message history
-- `agent.client` - the LLM client
-- `agent.fork(system_prompt:)` - create a sub-agent
-
-## MCP Configuration
-
-Configure MCP servers in `~/.elelem/mcp.json` or `.elelem/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "gitlab": {
-      "command": "npx",
-      "args": ["-y", "@anthropics/gitlab-mcp"],
-      "env": {
-        "GITLAB_TOKEN": "${GITLAB_TOKEN}"
-      }
-    },
-    "remote": {
-      "type": "http",
-      "url": "https://mcp.example.com/sse"
-    }
-  }
-}
+$ git clone https://git.mokhan.ca/elelem/elelem.git
 ```
 
-HTTP servers support OAuth authentication automatically.
-
-## Known Limitations
-
-* Assumes the current directory is a Git repository.
-* No sandboxing – the LLM can run arbitrary commands.
-* Error handling is minimal; exceptions are returned as an `error` field.
-
-## Contributing
-
-Send me an email. For instructions see https://git-send-email.io/.
+Send me a patch via email. For instructions see https://git-send-email.io/.
 
 ## License
 

data/exe/elelem

@@ -1,7 +1,13 @@
 #!/usr/bin/env -S ruby -W0
 # frozen_string_literal: true
 
-require "elelem"
+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 }
 

data/lib/elelem/agent.rb

@@ -2,94 +2,100 @@
 
 module Elelem
   class Agent
-    attr_reader :conversation, :client, :toolbox, :terminal, :commands
-    attr_writer :terminal, :toolbox, :commands
+    attr_reader :conversation, :toolbox, :output
+    attr_accessor :provider
 
-    def initialize(client, toolbox: Toolbox.new, terminal: nil, system_prompt: nil, commands: nil)
-      @client = client
+    def initialize(provider, toolbox: Toolbox.new, output: NullOutput.new, system_prompt: nil)
+      @provider = provider
       @toolbox = toolbox
-      @commands = commands || Commands.new
-      @terminal = terminal
-      @conversation = Conversation.new
-      @system_prompt = system_prompt
-    end
-
-    def repl
-      terminal.say "elelem v#{VERSION}"
-      loop do
-        input = terminal.ask("> ")
-        break if input.nil?
-        next if input.empty?
-        input.start_with?("/") ? command(input) : turn(input)
-      end
-    end
-
-    def command(input)
-      parts = input.delete_prefix("/").split(" ", 2)
-      name, args = parts[0], parts[1]
-      commands.run(name, args) || terminal.say(commands.names.join(" "))
+      @output = output
+      @conversation = Transcript.new(system_prompt: system_prompt)
     end
 
     def context
-      @conversation.to_a(system_prompt: system_prompt)
+      @conversation.to_a
     end
 
-    def fork(system_prompt:)
-      Agent.new(client, toolbox: toolbox, terminal: terminal, system_prompt: system_prompt)
+    def turn(prompt)
+      @conversation.add(role: "user", content: prompt)
+      content = run_until_done([])
+      @conversation.add(role: "assistant", content: content)
+      content
     end
 
-    def turn(input)
-      @conversation.add(role: "user", content: input)
-      ctx = []
-      content = nil
+    private
 
+    def run_until_done(ctx)
       loop do
-        terminal.waiting
-        content, tool_calls = fetch_response(ctx)
-        terminal.say(terminal.markdown(content))
-        break if tool_calls.empty?
-
-        ctx << { role: "assistant", content: content, tool_calls: tool_calls }.compact
-        tool_calls.each do |tool_call|
-          ctx << { role: "tool", tool_call_id: tool_call[:id], content: process(tool_call).to_json }
-        end
+        content, tool_calls = fetch_and_say(ctx)
+        return content if tool_calls.empty?
+
+        ctx.concat(tool_turn(content, tool_calls))
       end
+    end
 
-      @conversation.add(role: "assistant", content: content)
-      content
+    def fetch_and_say(ctx)
+      output.waiting
+      content, tool_calls = fetch_response(ctx)
+      output.say(content, as: :markdown)
+      [content, tool_calls]
     end
 
-    private
+    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, args = tool_call[:name], tool_call[:arguments]
-      terminal.say toolbox.header(name, args)
-      toolbox.run(name.to_s, args)
+      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
 
-      client.fetch(@conversation.to_a(system_prompt: system_prompt) + ctx, toolbox.to_a) do |event|
-        case event[:type]
-        when "saying"
-          content << event[:text].to_s
-        when "thinking"
-          terminal.print(terminal.think(event[:text]))
-        when "tool_call"
-          tool_calls << { id: event[:id], name: event[:name], arguments: event[:arguments] }
-        end
-      end
+    def messages(ctx)
+      @conversation.to_a(ctx)
+    end
 
-      [content, tool_calls]
-    rescue => e
-      terminal.say "\n  ✗ #{e.message}"
-      ["Error: #{e.message} #{e.backtrace.join("\n")}", []]
+    def fetch_error(error)
+      warn_and_say(error)
+      ["Error: #{error.message}", []]
+    end
+
+    def handle_event(event, content, tool_calls)
+      case event[:type]
+      when "saying" then content << event[:text].to_s
+      when "thinking" then output.thinking(event[:text])
+      when "doing" then tool_calls << { id: event[:id], name: event[:name], arguments: event[:arguments] }
+      end
     end
 
-    def system_prompt
-      @system_prompt || SystemPrompt.new.render
+    def warn_and_say(error)
+      Elelem.logger.warn("agent: #{error.message}")
+      output.say(error.message, as: :error)
     end
   end
 end

data/lib/elelem/cli.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "elelem"
+require "io/console"
+require "optparse"
+require "reline"
+
+module Elelem
+  class CLI
+    COMMANDS = %w[chat ask files help].freeze
+    USAGE = <<~TEXT
+      \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
+    private_constant :USAGE
+
+    def initialize(args, provider: "stub")
+      @provider = provider
+      @args = parse(args)
+    end
+
+    def run
+      command = @args.shift || "chat"
+      abort "Unknown command: #{command}" unless COMMANDS.include?(command)
+      send(command)
+    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
+    end
+
+    def help
+      puts @parser
+    end
+
+    def chat
+      Elelem.start(provider: @provider)
+    rescue StandardError, ScriptError => e
+      warn_and_abort(e)
+    end
+
+    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
+
+    def piped?
+      !$stdout.tty?
+    end
+
+    def output_for_ask
+      Elelem::Output.new(stream: piped? ? $stderr : $stdout)
+    end
+
+    def prompt_for_ask
+      prompt = @args.join(" ")
+      $stdin.stat.pipe? ? "#{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>)
+    end
+  end
+end

data/lib/elelem/commands.rb

@@ -2,19 +2,33 @@
 
 module Elelem
   class Commands
-    def initialize
-      @registry = {}
+    include Enumerable
+
+    def initialize(registry = {})
+      @registry = registry
+    end
+
+    def clear!
+      @registry.clear
     end
 
-    def register(name, description: "", &handler)
-      @registry[name] = { description: description, handler: handler }
+    def register(name, description: "", completions: nil, &handler)
+      @registry[name] = SlashCommand.new(name, description, completions, &handler)
+    end
+
+    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.select { |o| o.start_with?(partial) }
     end
 
     def run(name, args = nil)
-      entry = @registry[name]
-      return false unless entry
+      command = command_for(name)
+      return false unless command
 
-      entry[:handler].arity == 0 ? entry[:handler].call : entry[:handler].call(args)
+      command.call(args)
       true
     end
 
@@ -23,11 +37,13 @@ module Elelem
     end
 
     def each
-      @registry.each { |name, entry| yield "/#{name}", entry[:description] }
+      @registry.each { |name, command| yield "/#{name}", command.description }
     end
 
-    def include?(name)
-      @registry.key?(name)
+    private
+
+    def command_for(name)
+      @registry[name]
     end
   end
 end

data/lib/elelem/config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Config
+    extend SingleForwardable
+
+    def_single_delegators :default, :build_provider, :build_session, :apply, :reload, :names
+
+    def self.default
+      @default ||= Registry.new
+    end
+  end
+
+  def self.configure(&)
+    Config.default.configure(&)
+  end
+end

data/lib/elelem/conversation.rb

@@ -10,6 +10,7 @@ module Elelem
 
     def add(role:, content:, **extra)
       raise ArgumentError, "invalid role: #{role}" unless ROLES.include?(role)
+
       @messages << { role: role, content: content, **extra }.compact
     end
 

data/lib/elelem/input.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "reline"
+
+module Elelem
+  class Input
+    def initialize(commands: [])
+      @commands = commands
+      Reline.autocompletion = true
+      Reline.completion_proc = ->(target, preposing) { complete(target, preposing) }
+    end
+
+    def ask(prompt)
+      Reline.readline(prompt, true)&.strip
+    end
+
+    def interactive?
+      $stdin.tty?
+    end
+
+    private
+
+    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?(" ")
+
+      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)
+    end
+
+    def complete_files(target)
+      output, = Open3.capture2("bash", "-c", "compgen -f #{Shellwords.escape(target)}")
+      output.lines.map(&:strip).first(20)
+    end
+  end
+end

data/lib/elelem/null_input.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Elelem
+  class NullInput
+    def ask(_prompt) = nil
+    def interactive? = false
+  end
+end