elelem-server 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ccf8d43f79bf8e8a3c5c138a05e9e1887d7e212a8ccdef1d498de8133a4c13ca
+  data.tar.gz: 5658cacb63bba0bce48f86b5ce948a1e6e18981caf7e012ddcabc6d5a1e3ec76
+SHA512:
+  metadata.gz: 989664ee67bf8bc7d48da210b540b14e81e86aaf53a24fa300c61cc36496fade39170f4e7919d59c48bd3cbcf43b3f7cf6754d2f59117423a24a6e370fce5a81
+  data.tar.gz: bf048a10f1f83129bb9e8baf79f5a7cabd959d845a4a996fc34fffa18674609a57c242821b250f4bc3f610aa5abf570a08a9ea841c4239fcbd7554040c67e769

data/.rspec

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 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/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)

data/lib/elelem/server/version.rb

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

data/lib/elelem/server/web_terminal.rb

@@ -0,0 +1,80 @@
+# 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 ask(prompt)
+        emit("prompt", prompt)
+        @answers.pop
+      end
+
+      def thinking(text)
+        emit("thinking", text)
+      end
+
+      def say(text, as: nil)
+        text = "\n  ✗ #{text}" if as == :error
+        emit("content", text)
+      end
+
+      def doing(name, args, state: "+")
+        say "#{state} #{name}(#{args})"
+      end
+
+      def waiting
+      end
+
+      def print(text)
+        emit("content", 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
+
+      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

data/lib/elelem/server.rb

@@ -0,0 +1,232 @@
+# 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)
+      llm_provider = Config.build_provider(provider)
+      web_terminal = WebTerminal.new
+      agent = Agent.new(llm_provider, toolbox: toolbox, output: web_terminal, input: web_terminal)
+      Config.apply(agent)
+      new(agent, port: port).start
+    end
+
+    def initialize(agent, port: 4567, address: "0.0.0.0")
+      @agent = agent
+      @port = port
+      @address = address
+      @terminal = agent.output
+    end
+
+    def start
+      server = WEBrick::HTTPServer.new(
+        Port: @port,
+        BindAddress: @address,
+        Logger: WEBrick::Log.new(File::NULL),
+        AccessLog: []
+      )
+      server.mount_proc("/", &method(:index))
+      server.mount_proc("/events", &method(:events))
+      server.mount_proc("/message", &method(:message))
+      server.mount_proc("/answer", &method(:answer))
+
+      trap("INT") { server.shutdown }
+      $stdout.puts "elelem v#{VERSION} listening on http://#{@address}:#{@port}"
+      server.start
+    end
+
+    private
+
+    def index(_req, res)
+      res.content_type = "text/html; charset=utf-8"
+      res.body = INDEX
+    end
+
+    def events(_req, res)
+      res.content_type = "text/event-stream"
+      res["Cache-Control"] = "no-cache"
+      res.chunked = true
+      res.body = ->(out) { stream(out) }
+    end
+
+    def stream(out)
+      events = @terminal.subscribe
+      loop do
+        out.write("data: #{JSON.dump(events.pop)}\n\n")
+      end
+    rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+      nil
+    ensure
+      @terminal.unsubscribe(events)
+    end
+
+    def message(req, res)
+      text = JSON.parse(req.body)["text"].to_s
+      Thread.new do
+        @agent.turn(text)
+      rescue => e
+        @terminal.say("Error: #{e.message}")
+      ensure
+        @terminal.done
+      end
+      res.status = 204
+    end
+
+    def answer(req, res)
+      @terminal.answer(JSON.parse(req.body)["text"].to_s)
+      res.status = 204
+    end
+
+    INDEX = <<~HTML
+      <!doctype html>
+      <html lang="en">
+      <head>
+      <meta charset="utf-8">
+      <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+      <title>elelem</title>
+      <style>
+        :root { color-scheme: dark; }
+        * { box-sizing: border-box; }
+        body {
+          margin: 0; height: 100dvh; display: flex; flex-direction: column;
+          background: #16161a; color: #e6e6e6;
+          font: 16px/1.55 ui-sans-serif, system-ui, -apple-system, sans-serif;
+        }
+        #log { flex: 1; overflow-y: auto; padding: 1rem; -webkit-overflow-scrolling: touch; }
+        .msg { max-width: 46rem; margin: 0 auto 1rem; padding: .65rem .85rem; border-radius: .6rem; }
+        .user { background: #2d3a4f; }
+        .assistant { background: #22222a; }
+        .thinking { opacity: .55; font-style: italic; white-space: pre-wrap; }
+        .msg pre {
+          background: #0d0d10; padding: .7rem; border-radius: .4rem;
+          overflow-x: auto; font-size: .875rem;
+        }
+        .msg code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+        .prompt { max-width: 46rem; margin: 0 auto 1rem; padding: .85rem; border-radius: .6rem; background: #4a3a1e; }
+        .prompt button {
+          font-size: 1rem; padding: .7rem 1.4rem; margin: .5rem .5rem 0 0;
+          border: 0; border-radius: .5rem; color: #fff; touch-action: manipulation;
+        }
+        .allow { background: #2f7d4f; }
+        .deny { background: #8c3535; }
+        form { display: flex; gap: .5rem; padding: .75rem; padding-bottom: max(.75rem, env(safe-area-inset-bottom));
+               border-top: 1px solid #2c2c33; background: #1b1b20; }
+        textarea {
+          flex: 1; resize: none; font: inherit; padding: .6rem; border-radius: .5rem;
+          border: 1px solid #35353d; background: #101014; color: inherit;
+        }
+        button.send { font-size: 1rem; padding: .6rem 1.2rem; border: 0; border-radius: .5rem; background: #3b6ea5; color: #fff; }
+      </style>
+      </head>
+      <body>
+      <div id="log"></div>
+      <form id="composer">
+        <textarea id="input" rows="1" placeholder="Message elelem…" autocapitalize="sentences"></textarea>
+        <button class="send" type="submit">Send</button>
+      </form>
+      <script>
+      const log = document.getElementById("log");
+      const input = document.getElementById("input");
+      let current = null;
+
+      const atBottom = () => log.scrollHeight - log.scrollTop - log.clientHeight < 80;
+      const scroll = (was) => { if (was) log.scrollTop = log.scrollHeight; };
+
+      function escape(text) {
+        return text.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c]);
+      }
+
+      function render(text) {
+        return escape(text)
+          .replace(/```(\\w*)\\n([\\s\\S]*?)```/g, (_m, _lang, code) => "<pre><code>" + code + "</code></pre>")
+          .replace(/`([^`\\n]+)`/g, "<code>$1</code>")
+          .replace(/\\*\\*([^*]+)\\*\\*/g, "<strong>$1</strong>")
+          .replace(/\\n/g, "<br>");
+      }
+
+      function bubble(cls) {
+        const was = atBottom();
+        const el = document.createElement("div");
+        el.className = "msg " + cls;
+        log.appendChild(el);
+        scroll(was);
+        return el;
+      }
+
+      function append(cls, text) {
+        if (!current || current.dataset.cls !== cls) {
+          current = bubble(cls);
+          current.dataset.cls = cls;
+          current.dataset.raw = "";
+        }
+        const was = atBottom();
+        current.dataset.raw += text;
+        current.innerHTML = render(current.dataset.raw);
+        scroll(was);
+      }
+
+      function askPermission(text) {
+        current = null;
+        const was = atBottom();
+        const el = document.createElement("div");
+        el.className = "prompt";
+        el.innerHTML = "<div>" + escape(text) + "</div>";
+        const respond = (answer) => {
+          el.querySelectorAll("button").forEach((b) => b.remove());
+          el.insertAdjacentHTML("beforeend", "<div><em>" + answer + "</em></div>");
+          fetch("/answer", { method: "POST", body: JSON.stringify({ text: answer }) });
+        };
+        const allow = document.createElement("button");
+        allow.className = "allow";
+        allow.textContent = "Allow";
+        allow.onclick = () => respond("y");
+        const deny = document.createElement("button");
+        deny.className = "deny";
+        deny.textContent = "Deny";
+        deny.onclick = () => respond("n");
+        el.append(allow, deny);
+        log.appendChild(el);
+        scroll(was);
+      }
+
+      new EventSource("/events").onmessage = (e) => {
+        const event = JSON.parse(e.data);
+        if (event.type === "content") append("assistant", event.text);
+        else if (event.type === "thinking") append("thinking", event.text);
+        else if (event.type === "prompt") askPermission(event.text);
+        else if (event.type === "done") current = null;
+      };
+
+      document.getElementById("composer").onsubmit = (e) => {
+        e.preventDefault();
+        const text = input.value.trim();
+        if (!text) return;
+        append("user", text);
+        current = null;
+        input.value = "";
+        fetch("/message", { method: "POST", body: JSON.stringify({ text: text }) });
+      };
+
+      input.addEventListener("keydown", (e) => {
+        if (e.key === "Enter" && !e.shiftKey) {
+          e.preventDefault();
+          document.getElementById("composer").requestSubmit();
+        }
+      });
+
+      input.addEventListener("input", () => {
+        input.style.height = "auto";
+        input.style.height = Math.min(input.scrollHeight, 160) + "px";
+      });
+      </script>
+      </body>
+      </html>
+    HTML
+  end
+end

data/spec/elelem/server/web_terminal_spec.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+RSpec.describe Elelem::Server::WebTerminal do
+  subject { described_class.new }
+
+  let(:events) { subject.subscribe }
+
+  before { events }
+
+  def drain(queue = events)
+    [].tap { |collected| collected << queue.pop until queue.empty? }
+  end
+
+  describe "#interactive?" do
+    it { expect(subject).to be_interactive }
+  end
+
+  describe "#say" do
+    it "emits content" do
+      subject.say("hello")
+      expect(drain).to eq([{ type: "content", text: "hello" }])
+    end
+
+    it "ignores blank text" do
+      subject.say("  ")
+      subject.say(nil)
+      expect(drain).to be_empty
+    end
+
+    it "strips ANSI colour codes meant for a terminal" do
+      subject.say("+ \e[36mexecute\e[0m(...)")
+      expect(drain).to eq([{ type: "content", text: "+ execute(...)" }])
+    end
+
+    it "accepts the as: keyword like Terminal#say" do
+      subject.say("hello", as: :markdown)
+      expect(drain).to eq([{ type: "content", text: "hello" }])
+    end
+  end
+
+  describe "#thinking" do
+    it "emits a thinking event" do
+      subject.thinking("pondering")
+      expect(drain).to eq([{ type: "thinking", text: "pondering" }])
+    end
+  end
+
+  describe "#display_file" do
+    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
+    it "emits a turn boundary" do
+      subject.done
+      expect(drain).to eq([{ type: "done" }])
+    end
+  end
+
+  describe "#waiting" do
+    it "is a no-op" do
+      subject.waiting
+      expect(drain).to be_empty
+    end
+  end
+
+  describe "multiple subscribers" do
+    it "every subscriber receives every event" do
+      other = subject.subscribe
+      subject.say("broadcast")
+      expect(drain).to eq([{ type: "content", text: "broadcast" }])
+      expect(drain(other)).to eq([{ type: "content", text: "broadcast" }])
+    end
+
+    it "stops delivering after unsubscribe" do
+      subject.unsubscribe(events)
+      subject.say("gone")
+      expect(drain).to be_empty
+    end
+  end
+
+  describe "#ask" do
+    it "emits a prompt and blocks until answered" do
+      thread = Thread.new { subject.ask("Allow?") }
+      expect(events.pop).to eq({ type: "prompt", text: "Allow?" })
+      subject.answer("n")
+      expect(thread.value).to eq("n")
+    end
+  end
+end

data/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

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: elelem-server
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- mo khan
+bindir: exe
+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.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !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: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+description: A web UI server plugin for elelem.
+email:
+- mo@mokhan.ca
+executables:
+- elelem-server
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE.txt
+- Rakefile
+- exe/elelem-server
+- lib/elelem/server.rb
+- lib/elelem/server/version.rb
+- lib/elelem/server/web_terminal.rb
+- spec/elelem/server/web_terminal_spec.rb
+- spec/spec_helper.rb
+homepage: https://src.mokhan.ca/elelem/server
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://src.mokhan.ca/elelem/server
+  source_code_uri: https://src.mokhan.ca/elelem/server
+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: A web UI server plugin for elelem.
+test_files: []