relay.app 0.1.0

data/app/routes/sign_in.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Relay::Routes
+  ##
+  # Handles authentication for the sign-in form.
+  class SignIn < Base
+    include Relay::Models
+
+    ##
+    # Authenticates a user and stores their session
+    # @return [void]
+    def call
+      user = find_user
+      if user&.authenticate(params["password"])
+        sign_in(user)
+        r.redirect("/")
+      else
+        r.redirect("/sign-in")
+      end
+    end
+
+    private
+
+    ##
+    # Finds the user for the submitted email address
+    # @return [Relay::Models::User, nil]
+    def find_user
+      Relay::Models::User.where(email: params["email"] || params["username"]).first
+    end
+
+    ##
+    # Persists the authenticated user in the session
+    # @param [Relay::Models::User] user
+    # @return [void]
+    def sign_in(user)
+      session["user_id"] = user.id
+    end
+  end
+end

data/app/routes/upload_attachment.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Relay::Routes
+  class UploadAttachment < Base
+    prepend Relay::Hooks::RequireUser
+
+    def call
+      raise ArgumentError, attachment.unsupported_message unless attachment.type_supported?(filename:, type:)
+      attachment.attach(io: request.body, filename:, type:)
+      response.status = 200
+      response["content-type"] = "text/html"
+      partial("fragments/input", locals: {swap_oob: false})
+    rescue ArgumentError => e
+      attachment.error = e.message
+      response.status = 422
+      response["content-type"] = "text/html"
+      partial("fragments/input", locals: {swap_oob: false})
+    end
+
+    private
+
+    def filename
+      value = request.get_header("HTTP_X_FILE_NAME").to_s
+      value = CGI.unescape(value)
+      raise ArgumentError, "a file is required" if value.empty?
+      value
+    end
+
+    def type
+      request.get_header("CONTENT_TYPE")
+    end
+  end
+end

data/app/routes/websocket/connection.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "protocol/websocket/message"
+
+class Relay::Routes::Websocket
+  module Connection
+    ##
+    # Establishes the WebSocket connection and handles incoming messages
+    # @param [Async::WebSocket::Adapters::Rack] conn
+    #  The WebSocket connection object
+    # @param [LLM::Provider] llm
+    #  The selected LLM provider
+    # @param [Relay::Models::Context] ctx
+    #  The current context
+    # @return [void]
+    def on_connect(conn, llm, ctx, params)
+      vars[:messages] = ctx.messages
+      write(conn, fragment(:status, status_bar(ctx:)))
+      while (message = conn.read)
+        dispatch(conn, ctx, parse_message(message), params)
+      end
+    rescue EOFError, Protocol::WebSocket::ClosedError
+      nil
+    ensure
+      @task = nil
+    end
+
+    ##
+    # Dispatches an incoming websocket payload to the appropriate handler.
+    # @param [Async::WebSocket::Adapters::Rack] conn
+    #  The WebSocket connection object
+    # @param [Relay::Models::Context] ctx
+    #  The current context
+    # @param [Hash] payload
+    #  The parsed websocket payload
+    # @param [Hash] params
+    #  The mutable request params for the current turn
+    # @return [void]
+    def dispatch(conn, ctx, payload, params)
+      case
+      when interrupt?(payload) then interrupt!(conn, ctx)
+      when request_in_flight?
+        write(conn, fragment(:status, status_bar(status: "Busy", ctx:)))
+      else
+        @task = Async { on_message(conn, ctx, payload, params) }
+      end
+    end
+
+    ##
+    # Writes an HTML fragment to the websocket as a text frame
+    # @param [Async::WebSocket::Adapters::Rack] conn
+    #  The WebSocket connection object
+    # @param [String] message
+    #  The rendered HTML fragment
+    # @return [void]
+    def write(conn, message)
+      conn.write(Protocol::WebSocket::TextMessage.new(String(message)))
+      conn.flush
+    rescue Errno::EPIPE, IOError, Protocol::WebSocket::ClosedError
+      nil
+    end
+
+    ##
+    # Reads an incoming message, sends it to the LLM session, and handles any function calls
+    # @param [Async::WebSocket::Adapters::Rack] conn
+    #  The WebSocket connection object
+    # @param [Relay::Models::Context] ctx
+    #  The current context
+    # @param [String] message
+    #  The incoming message
+    # @return [void]
+    def on_message(conn, ctx, payload, params)
+      file = attachment_from_payload(payload) || attachment.consume
+      prompt = build_prompt(ctx, payload["message"], file)
+      return if prompt.empty?
+      vars[:messages].concat [{role: :user, content: prompt}, {role: :assistant, content: +""}]
+      write(conn, fragment(:status, status_bar(status: "Thinking...", ctx:)))
+      write(conn, fragment(:remove_empty_state)) if vars[:messages].length == 2
+      write(conn, fragment(:append_message, message: vars[:messages][-2]))
+      write(conn, fragment(:append_message, message: vars[:messages][-1]))
+      write(conn, fragment(:input))
+      yield_tools(ctx) do |tools|
+        params[:tools] = tools
+        wait_with_heartbeat(conn, proc { talk(ctx, prompt, params) })
+        resolve_functions(ctx, conn, params)
+      end
+      write(conn, fragment(:status, status_bar(ctx:)))
+      @contexts = nil
+      write(conn, fragment(:contexts, contexts: contexts))
+    rescue LLM::Interrupt
+      on_interrupt(conn, ctx)
+    rescue LLM::NoSuchRegistryError, LLM::NoSuchModelError
+      write(conn, fragment(:status, status_bar(cost: "unknown")))
+    rescue => e
+      pp e.class, e.message, e.backtrace
+      write(conn, fragment(:status, status_bar(status: "#{e.class}: #{e.message}")))
+    ensure
+      @task = nil
+    end
+
+    ##
+    # Sends a message to the LLM session
+    # @param [Relay::Models::Context] ctx
+    #  The current context
+    # @param [String] message
+    #  The message to send
+    # @return [void]
+    def talk(ctx, prompt, params)
+      if ctx.messages.empty?
+        ctx.talk initial_prompt(prompt), params
+      else
+        ctx.talk(prompt, params)
+      end
+    end
+
+    ##
+    # Invokes any pending function calls in the LLM session
+    # @param [Relay::Models::Context] ctx
+    #  The current context
+    # @param [Async::WebSocket::Adapters::Rack] conn
+    #  The WebSocket connection object
+    # @return [void]
+    def resolve_functions(ctx, conn, params)
+      return if ctx.functions.empty?
+      returns = wait_with_heartbeat(conn, ctx.wait(:task))
+      wait_with_heartbeat(conn, proc { ctx.talk(returns, params) })
+      if ctx.functions.any?
+        resolve_functions(ctx, conn, params)
+      end
+    end
+
+    ##
+    # Appends a streamed assistant chunk to the last assistant message and re-renders chat
+    # @param [Async::WebSocket::Adapters::Rack] conn
+    #  The WebSocket connection object
+    # @param [String] chunk
+    #  The streamed assistant text chunk
+    # @return [void]
+    def stream(conn, chunk)
+      message = vars[:messages].reverse_each.find { _1[:role] == :assistant }
+      message[:content] << chunk
+      write conn, fragment(:replace_last_message, message:)
+    end
+
+    ##
+    # Renders a websocket fragment using the retained fragment state
+    # @param [Symbol] name
+    #  The fragment name
+    # @param [Hash] locals
+    #  The local values to merge into the retained fragment state
+    # @return [String]
+    #  The rendered HTML fragment
+    def fragment(name, locals = nil, **kwargs)
+      vars.merge!((locals || {}).merge(kwargs))
+      case name
+      when :append_message then partial("fragments/append_message", locals: vars)
+      when :chat then partial("fragments/stream", locals: vars)
+      when :contexts then partial("fragments/settings/replace_contexts", locals: vars)
+      when :input then partial("fragments/input", locals: {swap_oob: true})
+      when :remove_empty_state then partial("fragments/remove_empty_state")
+      when :replace_last_message then partial("fragments/replace_last_message", locals: vars)
+      when :status then partial("fragments/status", locals: vars.merge(swap_oob: true))
+      end
+    end
+
+    ##
+    # Parses an incoming websocket frame from HTMX and extracts the message text
+    # @param [Protocol::WebSocket::Message] message
+    #  The websocket message frame
+    # @return [String]
+    #  The message text, or an empty string if parsing fails
+    def parse_message(message)
+      JSON.parse(message.buffer)
+    rescue JSON::ParserError
+      {}
+    end
+
+    ##
+    # Returns the fragments variables
+    # @return [Hash]
+    def vars
+      @temp ||= {messages: []}
+    end
+
+    def request_in_flight?
+      @task&.alive?
+    end
+
+    ##
+    # Waits for a runnable to finish while sending websocket heartbeats
+    # @param [LLM::Function::ThreadGroup, Proc] runnable
+    #  The runnable value to wait for
+    # @param [Async::WebSocket::Adapters::Rack] conn
+    #  The WebSocket connection object
+    # @return [Array<LLM::Function::Return>, nil]
+    #  Returns thread-group values, or nil for proc work
+    def wait_with_heartbeat(conn, runner)
+      runnable = if Proc === runner
+        Async { runner.call }
+      elsif Array === runner
+        Async { runner }
+      else
+        runner
+      end
+      while runnable.alive?
+        write conn, "<!-- heartbeat -->"
+        pause(0.5)
+      end
+      runnable.wait
+    end
+
+    def pause(seconds)
+      Async::Task.current.sleep(seconds)
+    end
+
+    def build_prompt(ctx, message, file)
+      text = message.to_s.strip
+      return text if file.nil?
+      parts = []
+      parts << text unless text.empty?
+      parts << ctx.local_file(file.path)
+      parts
+    end
+
+    def attachment_from_payload(payload)
+      path = payload["attachment_path"].to_s
+      return if path.empty? || !File.file?(path)
+      Relay::Attachment.new(
+        name: payload["attachment_name"],
+        path:,
+        type: payload["attachment_type"]
+      )
+    end
+
+    ##
+    # @param [Relay::Models::Context] servers
+    # @yieldparam [Array<LLM::Tool>] tools
+    # @return [void]
+    def yield_tools(ctx)
+      servers = ctx.mcps
+      servers.each(&:start)
+      yield [*LLM::Tool.registry.reject(&:mcp?), *servers.flat_map(&:tools)]
+    ensure
+      servers&.each { _1.stop rescue nil }
+    end
+  end
+end

data/app/routes/websocket/interrupt.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class Relay::Routes::Websocket
+  module Interrupt
+    def interrupt?(payload)
+      payload["type"] == "interrupt"
+    end
+
+    def interrupt!(conn, ctx)
+      return unless request_in_flight?
+      ctx.interrupt!
+      write(conn, fragment(:status, status_bar(status: "Cancelling...", ctx:)))
+    end
+
+    def on_interrupt(conn, ctx)
+      message = vars[:messages].reverse_each.find { _1[:role] == :assistant }
+      if message && message[:content].to_s.empty?
+        message[:content] = "Request cancelled."
+        write(conn, fragment(:replace_last_message, message:))
+      end
+      write(conn, fragment(:status, status_bar(status: "Request cancelled", ctx:)))
+      write(conn, fragment(:input))
+    end
+  end
+end

data/app/routes/websocket/stream.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class Relay::Routes::Websocket
+  class Stream < LLM::Stream
+    ##
+    # @param [Async::WebSocket::Adapters::Rack] conn
+    #  The WebSocket connection object
+    # @param [Relay::Routes::Websocket] sock
+    #  The websocket route object
+    def initialize(conn, sock)
+      @conn = conn
+      @sock = sock
+    end
+
+    ##
+    # Writes a streamed text chunk
+    # @param [String] chunk
+    #  The streamed text chunk
+    # @return [void]
+    def on_content(chunk)
+      @sock.stream(@conn, chunk.to_s)
+    end
+
+    ##
+    # On tool call
+    # @return [void]
+    def on_tool_call(tool, error)
+      @sock.report_tool_status(@conn, tool)
+      queue << (error || tool.spawn(:task))
+    end
+
+    ##
+    # Reports compaction start in the chat status bar.
+    # @return [void]
+    def on_compaction(ctx, compactor)
+      @sock.write(@conn, @sock.fragment(:status, @sock.status_bar(status: "Compacting...", ctx:)))
+    end
+
+    ##
+    # Reports compaction completion with refreshed usage details.
+    # @return [void]
+    def on_compaction_finish(ctx, compactor)
+      @sock.write(@conn, @sock.fragment(:status, @sock.status_bar(status: "Compaction finished", ctx:)))
+    end
+  end
+end

data/app/routes/websocket.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Relay::Routes
+  class Websocket < Base
+    require_relative "websocket/connection"
+    require_relative "websocket/interrupt"
+    require_relative "websocket/stream"
+
+    prepend Relay::Hooks::RequireUser
+
+    include Interrupt
+    include Connection
+    include Relay::Tools
+
+    def call
+      Async::WebSocket::Adapters::Rack.open(request.env) do |conn|
+        context = ctx
+        stream = Relay::Routes::Websocket::Stream.new(conn, self)
+        params = {model: context[:model], stream:, tools: []}
+        on_connect conn, context.llm, context, params
+      end || upgrade_required
+    end
+
+    def tool_status(functions)
+      names = functions.filter_map(&:name).reject(&:empty?).uniq
+      return "Running tools…" if names.empty?
+      "Running #{names.join(", ")}…"
+    end
+
+    def report_tool_status(conn, tool)
+      write(conn, fragment(:status, status_bar(status: tool_status([tool]))))
+    end
+
+    private
+
+    def upgrade_required
+      response.status = 426
+      response["content-type"] = "text/plain"
+      response["upgrade"] = "websocket"
+      "Expected a WebSocket upgrade request\n"
+    end
+
+    def instructions
+      File.read File.join(root, "app", "prompts", "system.md")
+    end
+
+    def initial_prompt(message)
+      LLM::Prompt.new(llm) do
+        _1.system instructions
+        _1.user(Array === message ? message : message.to_s)
+      end
+    end
+
+    ##
+    # Returns a logging tracer
+    # @return [LLM::Tracer]
+    def logger(llm)
+      filename = format("%s-%s.log", llm.name, Date.today.strftime("%Y-%m-%d"))
+      LLM::Tracer::Logger.new(llm, path: File.join(root, "tmp", filename))
+    end
+  end
+end

data/app/tools/add_song.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Relay::Tools
+  class AddSong < LLM::Tool
+    include Relay::Tool
+
+    name "add-song"
+    description "Adds a new track from an artist, title, and YouTube link"
+    param :name, String, "The artist or performer name", required: true
+    param :title, String, "The track title", required: true
+    param :url, String, "A YouTube watch/share/embed URL", required: true
+
+    def call(name:, title:, url:)
+      entry = jukebox.add(name:, title:, track: url)
+      {
+        message: "Added jukebox entry",
+        entry:
+      }
+    end
+
+    private
+
+    def jukebox
+      @jukebox ||= Relay::Jukebox.new
+    end
+  end
+end

data/app/tools/juke_box.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Relay::Tools
+  ##
+  # Returns the built-in jukebox playlist and embeddable iframe HTML for
+  # each track. The playlist is stored in the songs table.
+  class JukeBox < LLM::Tool
+    include Relay::Tool
+
+    name "jukebox"
+    description "Returns a small built-in playlist of playable music videos"
+
+    ##
+    # @return [Array<Hash>]
+    def call
+      jukebox.load.map do |entry|
+        {
+          name: entry["name"],
+          title: entry["title"],
+          track: entry["track"],
+          html: Relay.erb("fragments/_iframe.erb", {entry:}),
+          directions:,
+        }
+      end
+    end
+
+    private
+
+    def jukebox
+      @jukebox ||= Relay::Jukebox.new
+    end
+
+    def directions
+      [
+        "Use the list to tell the user what songs are available.",
+        "When the user wants to play a specific track, embed that track's iframe HTML exactly as returned.",
+        "Do not use `data-play` attributes."
+      ]
+    end
+  end
+end

data/app/tools/relay_knowledge.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Relay::Tools
+  ##
+  # The {Relay::Tools::RelayKnowledge} tool provides the LLM
+  # with knowledge about Relay through its README documentation.
+  # This helps inform the LLM what about Relay is and what it does,
+  # since it is unlikely to be heard of by an LLM.
+  class RelayKnowledge < LLM::Tool
+    include Relay::Tool
+
+    name "relay-knowledge"
+    description "Returns Relay or llm.rb documentation so answers can cite project details"
+    param :topic, Enum["relay", "llm.rb"], "The knowledge topic", required: true
+
+    ##
+    # Provides the Relay documentation
+    # @return [Hash]
+    def call(topic:)
+      case topic
+      when "relay" then {directions:, documentation: relay_documentation}
+      when "llm.rb" then {directions:, documentation: llmrb_documentation}
+      else {error: "unknown topic: #{topic}"}
+      end
+    end
+
+    private
+
+    def relay_documentation
+      relay_resources.each_with_object({}) do |(key, url), h|
+        res = Net::HTTP.get_response URI.parse(url)
+        h[key] = res.body
+      end
+    end
+
+    def relay_resources
+      {"readme" => "https://raw.githubusercontent.com/llmrb/relay/refs/heads/main/README.md"}
+    end
+
+    def llmrb_documentation
+      llmrb_resources.each_with_object({}) do |(key, url), h|
+        res = Net::HTTP.get_response URI.parse(url)
+        h[key] = res.body
+      end
+    end
+
+    def llmrb_resources
+      {
+        "readme"   => "https://raw.githubusercontent.com/llmrb/llm.rb/refs/heads/main/README.md",
+        "deepdive" => "https://raw.githubusercontent.com/llmrb/llm.rb/refs/heads/main/resources/deepdive.md",
+        "changelog" => "https://raw.githubusercontent.com/llmrb/llm.rb/refs/heads/main/CHANGELOG.md"
+      }
+    end
+
+    def directions
+      "Reference links from the associated document in your response"
+    end
+  end
+end

data/app/tools/remove_song.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Relay::Tools
+  class RemoveSong < LLM::Tool
+    include Relay::Tool
+
+    name "remove-song"
+    description "Removes one or more matching tracks from the jukebox"
+    param :by, Enum["name", "title", "url"], "The jukebox field to match against", required: true
+    param :value, String, "The artist name, track title, or YouTube URL to remove", required: true
+
+    def call(by:, value:)
+      params = remove_params(by, value)
+      result = jukebox.remove(**params)
+      if result[:removed].zero?
+        {
+          ok: true,
+          by:,
+          value:,
+          message: "No matching jukebox entries were found; the requested song may already be absent",
+          removed: 0,
+          entries: []
+        }
+      else
+        {
+          ok: true,
+          by:,
+          value:,
+          message: "Removed #{result[:removed]} jukebox entr#{result[:removed] == 1 ? "y" : "ies"}",
+          removed: result[:removed],
+          entries: result[:entries]
+        }
+      end
+    end
+
+    private
+
+    def jukebox
+      @jukebox ||= Relay::Jukebox.new
+    end
+
+    def remove_params(by, value)
+      text = value.to_s.strip
+      raise ArgumentError, "value is required" if text.empty?
+      case by
+      when "name" then {name: text}
+      when "title" then {title: text}
+      when "url" then {track: jukebox.normalize_track(text)}
+      else raise ArgumentError, "unsupported match field"
+      end
+    end
+  end
+end

data/app/validators/mcp.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Relay::Validators
+  class MCP
+    def initialize(model)
+      @model = model
+    end
+
+    def call
+      validate_data
+      validate_transport_fields
+      validate_preset_fields
+    end
+
+    private
+
+    attr_reader :model
+
+    def validate_data
+      model.errors.add(:data, "is invalid") unless model.data.is_a?(Hash)
+    end
+
+    def validate_transport_fields
+      case model.transport
+      when "http"
+        model.errors.add(:url, "is required") if model.url.empty?
+      when "stdio"
+        model.errors.add(:command, "is required") if model.command.empty?
+      end
+    end
+
+    def validate_preset_fields
+      case model.data["preset"]
+      when "github"
+        model.errors.add(:token, "is required") if model.headers["Authorization"].to_s.delete_prefix("Bearer ").strip.empty?
+      when "forgejo"
+        model.errors.add(:url, "is required") if model.env["FORGEJO_URL"].to_s.strip.empty?
+        model.errors.add(:token, "is required") if model.env["FORGEJO_TOKEN"].to_s.strip.empty?
+      end
+    end
+  end
+end

data/app/views/fragments/_append_message.erb

@@ -0,0 +1 @@
+<div hx-swap-oob="beforeend:#chatbot-messages"><%== partial("fragments/message", locals: {message:}) %></div>