Commit `d7ba7b4`

mo khan <mo@mokhan.ca>

2026-09-07 02:35:35

feat: package as elelem-server plugin gem

Extracted from elelem core to keep core minimal and closed for modification. Fixes two Terminal contract bugs found in review: WebTerminal#say didn't accept the markdown: kwarg core's Agent#turn always passes (crashed every reply), and #display_file ignored the requested path, always emitting the fallback text instead of file contents. Claude-Session: https://claude.ai/code/session_01DUuj4amvRrPxDnHPHBkvz5

main

1 parent 59fda9f

Changed files (14)

exe

elelem-server

lib

elelem

server

version.rb

web_terminal.rb

server.rb

web_terminal.rb

spec

elelem

server

web_terminal_spec.rb

spec_helper.rb

.gitignore

.rspec

elelem-server.gemspec

Gemfile

Gemfile.lock

LICENSE.txt

Rakefile

exe/elelem-server

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "elelem/server"
+require "optparse"
+
+provider = ENV.fetch("ELELEM_PROVIDER", "stub")
+port = 4567
+
+OptionParser.new do |o|
+  o.banner = "Usage: elelem-server [options]"
+  o.on("-p", "--provider NAME", "Provider to use (default: #{provider})") { |v| provider = v }
+  o.on("--port PORT", Integer, "Port to listen on (default: #{port})") { |v| port = v }
+  o.on("-h", "--help", "Show this help") { puts o; exit }
+end.parse!(ARGV)
+
+Elelem::Server.serve(provider: provider, port: port)

lib/elelem/server/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Elelem
+  class Server
+    VERSION = "0.1.0"
+  end
+end

lib/elelem/server/web_terminal.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Elelem
+  class Server
+    class WebTerminal
+      def initialize
+        @subscribers = []
+        @mutex = Mutex.new
+        @answers = Queue.new
+      end
+
+      def subscribe
+        Queue.new.tap { |queue| @mutex.synchronize { @subscribers << queue } }
+      end
+
+      def unsubscribe(queue)
+        @mutex.synchronize { @subscribers.delete(queue) }
+      end
+
+      def interactive?
+        true
+      end
+
+      def quiet?
+        false
+      end
+
+      def ask(prompt)
+        emit("prompt", prompt)
+        @answers.pop
+      end
+
+      def think(text)
+        emit("thinking", text)
+        nil
+      end
+
+      def say(text, markdown: false)
+        emit("content", text)
+      end
+
+      def do(header)
+        gap
+        say header
+      end
+
+      def oops(error)
+        say "\n  ✗ #{error.message}"
+        Elelem.logger.warn("agent: #{error.message}\n#{error.backtrace.join("\n")}")
+      end
+
+      def print(text)
+        emit("content", text)
+      end
+
+      def markdown(text)
+        text
+      end
+
+      def display_file(path, fallback: nil)
+        content = File.read(path)
+        raise ArgumentError unless content.valid_encoding?
+
+        say(content)
+      rescue Errno::ENOENT, Errno::EISDIR, ArgumentError
+        say(fallback || path)
+      end
+
+      def answer(text)
+        @answers << text
+      end
+
+      def done
+        broadcast(type: "done")
+      end
+
+      def waiting; end
+
+      def gap; end
+
+      def newline(n: 1); end
+
+      private
+
+      def emit(type, text)
+        plain = text.to_s.gsub(/\e\[[0-9;]*[a-zA-Z]/, "")
+        return if plain.strip.empty?
+
+        broadcast(type: type, text: plain)
+      end
+
+      def broadcast(event)
+        @mutex.synchronize { @subscribers.each { |queue| queue << event } }
+      end
+    end
+  end
+end

lib/elelem/server.rb

@@ -1,7 +1,21 @@
 # frozen_string_literal: true
 
+require "elelem"
+require "json"
+require "webrick"
+
+require_relative "server/version"
+require_relative "server/web_terminal"
+
 module Elelem
   class Server
+    def self.serve(provider: "stub", port: 4567, toolbox: Toolbox.new)
+      client = Providers.build(provider)
+      agent = Agent.new(client, toolbox: toolbox, terminal: WebTerminal.new)
+      Plugins.setup!(agent)
+      new(agent, port: port).start
+    end
+
     def initialize(agent, port: 4567, address: "0.0.0.0")
       @agent = agent
       @port = port

lib/elelem/web_terminal.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module Elelem
-  class WebTerminal
-    def initialize
-      @subscribers = []
-      @mutex = Mutex.new
-      @answers = Queue.new
-    end
-
-    def subscribe
-      Queue.new.tap { |queue| @mutex.synchronize { @subscribers << queue } }
-    end
-
-    def unsubscribe(queue)
-      @mutex.synchronize { @subscribers.delete(queue) }
-    end
-
-    def interactive?
-      true
-    end
-
-    def quiet?
-      false
-    end
-
-    def ask(prompt)
-      emit("prompt", prompt)
-      @answers.pop
-    end
-
-    def think(text)
-      emit("thinking", text)
-      nil
-    end
-
-    def say(text)
-      emit("content", text)
-    end
-
-    def do(header)
-      gap
-      say header
-    end
-
-    def oops(error)
-      say "\n  ✗ #{error.message}"
-      Elelem.logger.warn("agent: #{error.message}\n#{error.backtrace.join("\n")}")
-    end
-
-    def print(text)
-      emit("content", text)
-    end
-
-    def markdown(text)
-      text
-    end
-
-    def display_file(path, fallback: nil)
-      say(fallback || path)
-    end
-
-    def answer(text)
-      @answers << text
-    end
-
-    def done
-      broadcast(type: "done")
-    end
-
-    def waiting; end
-
-    def gap; end
-
-    def newline(n: 1); end
-
-    private
-
-    def emit(type, text)
-      plain = text.to_s.gsub(/\e\[[0-9;]*[a-zA-Z]/, "")
-      return if plain.strip.empty?
-
-      broadcast(type: type, text: plain)
-    end
-
-    def broadcast(event)
-      @mutex.synchronize { @subscribers.each { |queue| queue << event } }
-    end
-  end
-end

spec/elelem/web_terminal_spec.rb → spec/elelem/server/web_terminal_spec.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-RSpec.describe Elelem::WebTerminal do
+RSpec.describe Elelem::Server::WebTerminal do
   subject { described_class.new }
 
   let(:events) { subject.subscribe }
@@ -35,6 +35,11 @@ RSpec.describe Elelem::WebTerminal do
       subject.say("+ \e[36mexecute\e[0m(...)")
       expect(drain).to eq([{ type: "content", text: "+ execute(...)" }])
     end
+
+    it "accepts the markdown keyword like Terminal#say" do
+      subject.say("hello", markdown: true)
+      expect(drain).to eq([{ type: "content", text: "hello" }])
+    end
   end
 
   describe "#think" do
@@ -52,10 +57,29 @@ RSpec.describe Elelem::WebTerminal do
   end
 
   describe "#display_file" do
-    it "emits the fallback" do
-      subject.display_file("a.rb", fallback: "contents")
+    it "emits the file's contents" do
+      Tempfile.create do |file|
+        file.write("contents")
+        file.flush
+        subject.display_file(file.path, fallback: "fallback")
+        expect(drain).to eq([{ type: "content", text: "contents" }])
+      end
+    end
+
+    it "emits the fallback when the file is missing" do
+      subject.display_file("/no/such/file.rb", fallback: "contents")
       expect(drain).to eq([{ type: "content", text: "contents" }])
     end
+
+    it "emits the fallback when the file is not valid UTF-8" do
+      Tempfile.create do |file|
+        file.binmode
+        file.write("\xFF\xFE\x00\x01")
+        file.flush
+        subject.display_file(file.path, fallback: "contents")
+        expect(drain).to eq([{ type: "content", text: "contents" }])
+      end
+    end
   end
 
   describe "#done" do

spec/spec_helper.rb

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