elelem 0.9.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cacca0937e61d8f45af65cf8652677b547bb2b6b12122087befd3ff7a1babd5e
-  data.tar.gz: 272d16dcfde24d82ce06d7c196969f548b969659bc0cbcf1d47cbbde900a450f
+  metadata.gz: 72a4cd636b39b6f30cc0520c3445a3b8748625fd5ca52f15b05d27349a0701b4
+  data.tar.gz: 12c55aaf15f42e7607fb60ed78500b44655ba6eaab857601ec58073378587866
 SHA512:
-  metadata.gz: 39645d1abc07c1878922d514b7adc244b3fe52ff9c597fb0c1c8ad16d19c5b3eb24f2e5bbaebf79169103d5cf369daa6954e96f16ccbd438c68e33b3544b0a22
-  data.tar.gz: 9983add61dcb73f7bf7e40c5ad13080a01b0e3391a4e7b163a166f534d87d7a5e973a62d304d1e15ecf25d27e5842fd402d9bdb959cf73bea2ebb8c256f3b419
+  metadata.gz: '018856c824b90cbbe658c3b117f683737f14c34f493ba3629281cd7318c11d039585b829e201a9a8bf591619747d2d6c7f1f3568f53a79c40222632a706303ac'
+  data.tar.gz: ab3132d4613f560dfb97e7bcfa406e5f49ac66f5e642ec85f77c1a25d030825f1a7d9f6401d54dd6eb3f767ec69506b8f114e3a269324fb5fd72f0ca97827a0d

data/README.md

@@ -1,76 +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 |
-|------|---------|---------|
-| [Ollama](https://ollama.ai/) | Default LLM provider | https://ollama.ai/download |
-| [glow](https://github.com/charmbracelet/glow) | Markdown rendering | `brew install glow` / `go install github.com/charmbracelet/glow@latest` |
-| [ctags](https://ctags.io/) | Repo map generation | `brew install universal-ctags` / `apt install universal-ctags` |
-| [ripgrep](https://github.com/BurntSushi/ripgrep) | Text search (`rg`) | `brew install ripgrep` / `apt install ripgrep` |
-| [fd](https://github.com/sharkdp/fd) | File discovery | `brew install fd` / `apt install fd-find` |
-| [ast-grep](https://ast-grep.github.io/) | Structural search (`sg`) | `brew install ast-grep` / `cargo install ast-grep` |
-| [Git](https://git-scm.com/) | Version control | `brew install git` / `apt install git` |
-
-**Required:** Git, Ollama (or another LLM provider)
-
-**Recommended:** glow, 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
 
@@ -88,68 +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
+$ git clone https://git.mokhan.ca/elelem/elelem.git
 ```
 
-### 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.
-
-## Toolbox Overview
-
-The `Toolbox` class is defined in `lib/elelem/toolbox.rb`. It supplies
-three tools, each represented by a JSON schema that the LLM can call.
-
-| Tool      | Purpose            | Parameters         |
-| --------- | ------------------ | ------------------ |
-| `read`    | Read file contents | `path`             |
-| `write`   | Write file         | `path`, `content`  |
-| `execute` | Run shell command  | `command`          |
-
-Aliases: `bash`, `sh`, `exec` → `execute`; `open` → `read`
-
-## 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/Rakefile

@@ -5,15 +5,4 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :files do
-  IO.popen(%w[git ls-files], chdir: __dir__, err: IO::NULL) do |ls|
-    ls.readlines.each do |f|
-      next if f.start_with?(*%w[bin/ spec/ pkg/ .git .rspec Gemfile Rakefile])
-      next if f.strip.end_with?(*%w[.toml .txt .md])
-
-      puts f
-    end
-  end
-end
-
 task default: %i[spec]

data/exe/elelem

@@ -1,85 +1,14 @@
 #!/usr/bin/env -S ruby -W0
 # frozen_string_literal: true
 
-require "elelem"
-require "optparse"
+require "elelem/cli"
 
-Signal.trap("INT") { exit 1 }
-
-class App
-  MODELS = {
-    "ollama" => "gpt-oss:latest",
-    "anthropic" => "claude-opus-4-5-20250514",
-    "vertex" => "claude-opus-4-5@20251101",
-    "openai" => "gpt-4o"
-  }.freeze
-
-  PROVIDERS = {
-    "ollama" => ->(model) { Elelem::Net::Ollama.new(model: model, host: ENV.fetch("OLLAMA_HOST", "localhost:11434")) },
-    "anthropic" => ->(model) { Elelem::Net::Claude.anthropic(model: model, api_key: ENV.fetch("ANTHROPIC_API_KEY")) },
-    "vertex" => ->(model) { Elelem::Net::Claude.vertex(model: model, project: ENV.fetch("GOOGLE_CLOUD_PROJECT"), region: ENV.fetch("GOOGLE_CLOUD_REGION", "us-east5")) },
-    "openai" => ->(model) { Elelem::Net::OpenAI.new(model: model, api_key: ENV.fetch("OPENAI_API_KEY")) }
-  }.freeze
-
-  def initialize(args)
-    @provider = "ollama"
-    @model = nil
-    @args = parse(args)
-  end
-
-  def run
-    command = @args.shift || "chat"
-    send(command.tr("-", "_"))
-  rescue NoMethodError
-    abort "Unknown command: #{command}"
-  end
-
-  private
-
-  def parse(args)
-    @parser = OptionParser.new do |o|
-      o.banner = "Usage: elelem [command] [options] [args]"
-      o.separator "\nCommands:"
-      o.separator "  chat              Interactive REPL (default)"
-      o.separator "  ask <prompt>      One-shot query (reads stdin if piped)"
-      o.separator "  files             Output files as XML (no options)"
-      o.separator "  help              Show this help"
-      o.separator "\nOptions:"
-      o.on("-p", "--provider NAME", "ollama, anthropic, vertex, openai") { |p| @provider = p }
-      o.on("-m", "--model NAME", "Override default model") { |m| @model = m }
-      o.on("-h", "--help") { puts o; exit }
-    end
-    @parser.parse!(args)
-  end
-
-  def help
-    puts @parser
-  end
-
-  def client
-    model = @model || MODELS.fetch(@provider)
-    PROVIDERS.fetch(@provider).call(model)
-  end
-
-  def chat = Elelem.start(client)
-
-  def ask
-    abort "Usage: elelem ask <prompt>" if @args.empty?
-    prompt = @args.join(" ")
-    prompt = "#{prompt}\n\n```\n#{$stdin.read}\n```" if $stdin.stat.pipe?
-    Elelem::Terminal.new.markdown Elelem.ask(client, prompt)
-  end
-
-  def files
-    files = $stdin.stat.pipe? ? $stdin.readlines : `git ls-files`.lines
-    puts "<documents>"
-    files.each_with_index do |line, i|
-      path = line.strip
-      next if path.empty? || !File.file?(path)
-      puts %Q{<document index="#{i + 1}"><source>#{path}</source><content><![CDATA[#{File.read(path)}]]></content></document>}
-    end
-    puts "</documents>"
-  end
+begin
+  require "elelem/builtins"
+rescue LoadError
+  warn "elelem: gem install elelem-builtins for the default tools and commands"
 end
 
-App.new(ARGV).run
+Signal.trap("INT") { exit 1 }
+
+Elelem::CLI.new(ARGV).run

data/lib/elelem/agent.rb

@@ -2,81 +2,42 @@
 
 module Elelem
   class Agent
-    COMMANDS = %w[/clear /context /init /reload /shell /exit /help].freeze
-    MAX_CONTEXT_MESSAGES = 50
-    INIT_PROMPT = <<~PROMPT
-      AGENTS.md generator. Analyze codebase and write AGENTS.md to project root.
+    attr_reader :conversation, :toolbox, :input, :output, :commands
+    attr_accessor :provider
 
-      # AGENTS.md Spec (https://agents.md/)
-      A file providing context and instructions for AI coding agents.
-
-      ## Recommended Sections
-      - Commands: build, test, lint commands
-      - Code Style: conventions, patterns
-      - Architecture: key components and flow
-      - Testing: how to run tests
-
-      ## Process
-      1. Read README.md if present
-      2. Identify language (Gemfile, package.json, go.mod)
-      3. Find test scripts (bin/test, npm test)
-      4. Check linter configs
-      5. Write concise AGENTS.md
-
-      Keep it minimal. No fluff.
-    PROMPT
-
-    attr_reader :history, :client, :toolbox, :terminal
-
-    def initialize(client, toolbox, terminal: nil, history: nil, system_prompt: nil)
-      @client = client
+    def initialize(provider, toolbox: Toolbox.new, input: NullInput.new, output: NullOutput.new, system_prompt: nil, commands: nil)
+      @provider = provider
       @toolbox = toolbox
-      @terminal = terminal || Terminal.new(commands: COMMANDS)
-      @history = history || []
-      @system_prompt = system_prompt
-      @memory = nil
-      register_task_tool
+      @commands = commands || Commands.new
+      @output = output
+      @input = input
+      @conversation = Conversation.new
+      @system_prompt = SystemPrompt.new(system_prompt)
     end
 
     def repl
-      terminal.say "elelem v#{VERSION}"
+      output.say "elelem v#{VERSION}"
       loop do
-        input = terminal.ask("> ")
-        break if input.nil?
-        next if input.empty?
-        input.start_with?("/") ? command(input) : turn(input)
+        line = input.ask("> ")
+        break if line.nil?
+        next if line.empty?
+        line.start_with?("/") ? command(line) : turn(line)
       end
     end
 
-    def command(input)
-      case input
-      when "/exit" then exit(0)
-      when "/init" then init_agents_md
-      when "/reload" then reload_source!
-      when "/shell"
-        transcript = start_shell
-        history << { role: "user", content: transcript } unless transcript.strip.empty?
-      when "/clear"
-        @history = []
-        @memory = nil
-        terminal.say "  → context cleared"
-      when "/context"
-        terminal.say JSON.pretty_generate(combined_history)
-      else
-        terminal.say COMMANDS.join(" ")
-      end
+    def context
+      @conversation.to_a(system_prompt: @system_prompt.render)
     end
 
-    def turn(input)
-      compact_if_needed
-      history << { role: "user", content: input }
+    def turn(prompt)
+      @conversation.add(role: "user", content: prompt)
       ctx = []
       content = nil
 
       loop do
-        terminal.waiting
+        output.waiting
         content, tool_calls = fetch_response(ctx)
-        terminal.say(terminal.markdown(content))
+        output.say(content, as: :markdown)
         break if tool_calls.empty?
 
         ctx << { role: "assistant", content: content, tool_calls: tool_calls }.compact
@@ -85,102 +46,50 @@ module Elelem
         end
       end
 
-      history << { role: "assistant", content: content }
+      @conversation.add(role: "assistant", content: content)
       content
     end
 
     private
 
-    def process(tool_call)
-      name, args = tool_call[:name], tool_call[:arguments]
-      terminal.say toolbox.header(name, args)
-      toolbox.run(name.to_s, args)
-    end
-
-    def register_task_tool
-      @toolbox.add("task",
-        description: "Delegate subtask to focused agent (complex searches, multi-file analysis)",
-        params: { prompt: { type: "string" } },
-        required: ["prompt"]
-      ) do |a|
-        sub = Agent.new(client, toolbox, terminal: terminal,
-          system_prompt: "Research agent. Search, analyze, report. Be concise.")
-        sub.turn(a["prompt"])
-        { result: sub.history.last[:content] }
-      end
-    end
-
-    def init_agents_md
-      sub = Agent.new(client, toolbox, terminal: terminal, system_prompt: INIT_PROMPT)
-      sub.turn("Generate AGENTS.md for this project")
-    end
-
-    def reload_source!
-      lib_dir = File.expand_path("..", __dir__)
-      original_verbose, $VERBOSE = $VERBOSE, nil
-      Dir["#{lib_dir}/**/*.rb"].sort.each { |f| load(f) }
-      $VERBOSE = original_verbose
-      @toolbox = Toolbox.new
-      Plugins.reload!(@toolbox)
-      register_task_tool
-    end
-
-    def start_shell
-      Tempfile.create do |file|
-        system("script", "-q", file.path, chdir: Dir.pwd)
-        strip_ansi(File.read(file.path))
-      end
+    def command(line)
+      parts = line.delete_prefix("/").split(" ", 2)
+      name, args = parts[0], parts[1]
+      commands.run(name, args) || output.say(commands.names.join(" "))
+    rescue => e
+      Elelem.logger.warn("agent: #{e.message}")
+      output.say(e.message, as: :error)
     end
 
-    def strip_ansi(text)
-      text.gsub(/^Script started.*?\n/, "")
-          .gsub(/\nScript done.*$/, "")
-          .gsub(/\e\[[0-9;]*[a-zA-Z]/, "")
-          .gsub(/\e\[\?[0-9]+[hl]/, "")
-          .gsub(/[\b]/, "")
-          .gsub(/\r/, "")
+    def process(tool_call)
+      name, args = tool_call[:name], tool_call[:arguments]
+      output.doing(toolbox.tool_for(name).name, args)
+      Elelem.logger.debug("agent: #{name}(#{args.inspect})")
+      result = toolbox.run(name.to_s, args)
+      Elelem.logger.debug("agent: #{name} -> #{result.inspect}")
+      result
     end
 
     def fetch_response(ctx)
-      content = ""
-      tool_calls = client.fetch(combined_history + ctx, toolbox.to_a) do |delta|
-        content += delta[:content].to_s
-        terminal.print(terminal.think(delta[:thinking])) if delta[:thinking]
+      content = String.new
+      tool_calls = []
+
+      provider.fetch(@conversation.to_a(system_prompt: @system_prompt.render) + ctx, toolbox.to_a) do |event|
+        case event[:type]
+        when "saying"
+          content << event[:text].to_s
+        when "thinking"
+          output.thinking(event[:text])
+        when "doing"
+          tool_calls << { id: event[:id], name: event[:name], arguments: event[:arguments] }
+        end
       end
+
       [content, tool_calls]
     rescue => e
-      terminal.say "\n  ✗ #{e.message}"
-      ["Error: #{e.message} #{e.backtrace.join("\n")}", []]
-    end
-
-    def combined_history
-      [{ role: "system", content: system_prompt }] + history
-    end
-
-    def system_prompt
-      @system_prompt || SystemPrompt.new(memory: @memory).render
-    end
-
-    def compact_if_needed
-      return if history.length <= MAX_CONTEXT_MESSAGES
-
-      terminal.say "  → compacting context"
-      keep = MAX_CONTEXT_MESSAGES / 2
-      old = history.first(history.length - keep)
-
-      to_summarize = @memory ? [{ role: "memory", content: @memory }, *old] : old
-      @memory = summarize(to_summarize)
-      @history = history.last(keep)
-    end
-
-    def summarize(messages)
-      text = messages.map { |message| { role: message[:role], content: message[:content] } }.to_json
-
-      String.new.tap do |buffer|
-        client.fetch([{ role: "user", content: "Summarize key facts:\n#{text}" }], []) do |d|
-          buffer << d[:content].to_s
-        end
-      end
+      Elelem.logger.warn("agent: #{e.message}")
+      output.say(e.message, as: :error)
+      ["Error: #{e.message}", []]
     end
   end
 end

data/lib/elelem/cli.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "elelem"
+require "io/console"
+require "optparse"
+require "reline"
+
+module Elelem
+  class CLI
+    COMMANDS = %w[chat ask files help].freeze
+
+    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 do |o|
+        o.banner = "Usage: #{File.basename($PROGRAM_NAME)} [command] [options] [args]"
+        o.separator "\nCommands:"
+        o.separator "  chat              Interactive REPL (default)"
+        o.separator "  ask <prompt>      One-shot query (reads stdin if piped)"
+        o.separator "  files             Output files as XML (no options)"
+        o.separator "  help              Show this help"
+        o.separator "\nOptions:"
+        o.on("-p", "--provider NAME", "Provider to use (default: #{@provider})") { |p| @provider = p }
+        o.on("-h", "--help", "Show this help") { puts o; exit }
+      end
+      @parser.parse!(args)
+    end
+
+    def help
+      puts @parser
+    end
+
+    def chat
+      Elelem.start(provider: @provider)
+    rescue => e
+      Elelem.logger.warn("cli: #{e.message}\n#{e.backtrace.join("\n")}")
+      abort "elelem: #{e.message}"
+    end
+
+    def ask
+      abort "Usage: elelem-chat ask <prompt>" if @args.empty?
+      prompt = @args.join(" ")
+      prompt = "#{prompt}\n\n```\n#{$stdin.read}\n```" if $stdin.stat.pipe?
+      piped = !$stdout.tty?
+      output = Elelem::Output.new(stream: piped ? $stderr : $stdout)
+      reply = Elelem.ask(prompt, provider: @provider, output: output)
+      abort "elelem: no reply" if reply.to_s.strip.empty?
+      Elelem::Output.new.say(reply, as: :markdown) if piped
+    rescue => e
+      Elelem.logger.warn("cli: #{e.message}\n#{e.backtrace.join("\n")}")
+      abort "elelem: #{e.message}"
+    end
+
+    def files
+      files = $stdin.stat.pipe? ? $stdin.readlines : `git ls-files`.lines
+      puts "<documents>"
+      files.each_with_index do |line, i|
+        path = line.strip
+        next if path.empty? || !File.file?(path)
+        puts %Q{<document index="#{i + 1}"><source>#{path}</source><document_content><![CDATA[#{File.read(path)}]]></document_content></document>}
+      end
+      puts "</documents>"
+     end
+  end
+end

data/lib/elelem/commands.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Elelem
+  class Commands
+    include Enumerable
+
+    def initialize(registry = {})
+      @registry = registry
+    end
+
+    def clear!
+      @registry.clear
+    end
+
+    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 && 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)
+      command = command_for(name)
+      return false unless command
+
+      command.call(args)
+      true
+    end
+
+    def names
+      @registry.keys.map { |name| "/#{name}" }
+    end
+
+    def each
+      @registry.each { |name, command| yield "/#{name}", command.description }
+    end
+
+    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_agent, :apply, :reload, :names
+
+    def self.default
+      @default ||= Registry.new
+    end
+  end
+
+  def self.configure(&block)
+    Config.default.configure(&block)
+  end
+end

data/lib/elelem/conversation.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Elelem
+  class Conversation
+    ROLES = %w[user assistant tool].freeze
+
+    def initialize
+      @messages = []
+    end
+
+    def add(role:, content:, **extra)
+      raise ArgumentError, "invalid role: #{role}" unless ROLES.include?(role)
+      @messages << { role: role, content: content, **extra }.compact
+    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
+    end
+  end
+end