robot_lab-web 0.2.6

data/lib/robot_lab/web/components/chat.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Web
+    module Components
+      # The chat page for one robot: transcript, composer, and the small vanilla
+      # SSE client that streams a run token-by-token into the transcript.
+      class Chat < Phlex::HTML
+        def initialize(name:)
+          @name = name
+        end
+
+        def view_template
+          h1(class: "flex items-center gap-2") do
+            a(href: "/", class: "inline-flex") do
+              render PhlexIcons::Hero::ArrowLeft.new(class: "w-6 h-6")
+            end
+            plain @name
+          end
+
+          div(id: "transcript", class: "transcript")
+
+          form(id: "composer", class: "composer", data: { stream_url: "/robots/#{@name}/stream" }) do
+            input(
+              type: "text", name: "message", id: "message",
+              placeholder: "Message #{@name}…", autocomplete: "off", autofocus: true
+            )
+            button(type: "submit", id: "send", class: "flex items-center gap-1.5") do
+              plain "Send"
+              render PhlexIcons::Hero::PaperAirplane.new(class: "w-4 h-4")
+            end
+          end
+
+          script { raw(safe(CLIENT_JS)) }
+        end
+
+        # The robot name only reaches JS via the form's data-stream-url attribute
+        # (set above), so this script needs no server interpolation.
+        CLIENT_JS = <<~'JS'
+          const csrf = document.querySelector('meta[name="csrf-token"]').content;
+          const streamUrl = document.getElementById('composer').dataset.streamUrl;
+          const transcript = document.getElementById('transcript');
+          const form = document.getElementById('composer');
+          const input = document.getElementById('message');
+          const send = document.getElementById('send');
+
+          function el(role, html) {
+            const d = document.createElement('div');
+            d.className = 'msg ' + role;
+            d.innerHTML = html;
+            transcript.appendChild(d);
+            transcript.scrollTop = transcript.scrollHeight;
+            return d;
+          }
+          const esc = (s) => String(s ?? '').replace(/[&<>]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
+          function header(role, robot) {
+            return '<div class="role">' + esc(role) + (robot ? ' · ' + esc(robot) : '') + '</div>';
+          }
+
+          // The robot bubble currently being filled by streamed :delta events.
+          let streaming = null;
+
+          function appendDelta(ev) {
+            if (!streaming) {
+              const bubble = el('robot', header('robot', ev.robot_name) + '<span class="body"></span>');
+              streaming = bubble.querySelector('.body');
+            }
+            streaming.textContent += ev.content ?? '';
+            transcript.scrollTop = transcript.scrollHeight;
+          }
+
+          function renderEvent(ev) {
+            const c = ev.content || {};
+            if (ev.role === 'delta') { appendDelta(ev); return; }
+            if (ev.role === 'user') return; // already shown optimistically
+
+            if (ev.role === 'robot' && streaming) {
+              streaming.textContent = typeof ev.content === 'string' ? ev.content : streaming.textContent;
+              streaming = null;
+              return;
+            }
+            streaming = null;
+
+            let body;
+            switch (ev.role) {
+              case 'tool_call':   body = esc(c.name) + '(' + esc(JSON.stringify(c.args)) + ')'; break;
+              case 'tool_result': body = c.error ? esc(c.name) + ' → error: ' + esc(c.error)
+                                                  : esc(c.name) + ' → ' + esc(JSON.stringify(c.result)); break;
+              case 'error':       body = esc(c.message || ev.content); break;
+              default:            body = esc(typeof ev.content === 'string' ? ev.content : JSON.stringify(ev.content));
+            }
+            el(ev.role, header(ev.role, ev.robot_name) + body);
+          }
+
+          async function streamRun(message) {
+            const res = await fetch(streamUrl, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'X-CSRF-Token': csrf },
+              body: 'message=' + encodeURIComponent(message)
+            });
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buf = '';
+            while (true) {
+              const { value, done } = await reader.read();
+              if (done) break;
+              buf += decoder.decode(value, { stream: true });
+              const frames = buf.split('\n\n');
+              buf = frames.pop();
+              for (const frame of frames) {
+                let type = 'message', data = '';
+                for (const line of frame.split('\n')) {
+                  if (line.startsWith('event:')) type = line.slice(6).trim();
+                  else if (line.startsWith('data:')) data += line.slice(5).trim();
+                }
+                if (!data) continue;
+                const payload = JSON.parse(data);
+                if (type === 'message') renderEvent(payload);
+                else if (type === 'error') el('error', header('error') + esc(payload.message));
+              }
+            }
+          }
+
+          form.addEventListener('submit', async (e) => {
+            e.preventDefault();
+            const message = input.value.trim();
+            if (!message) return;
+            streaming = null;
+            el('user', header('user') + esc(message));
+            input.value = '';
+            input.disabled = send.disabled = true;
+            try { await streamRun(message); }
+            catch (err) { el('error', header('error') + esc(err.message)); }
+            finally { input.disabled = send.disabled = false; input.focus(); }
+          });
+        JS
+      end
+    end
+  end
+end

data/lib/robot_lab/web/components/dashboard.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Web
+    module Components
+      # The dashboard: registered robots + the recent-activity feed.
+      class Dashboard < Phlex::HTML
+        def initialize(robots:, activity:)
+          @robots = robots
+          @activity = activity
+        end
+
+        def view_template
+          h1 { "Robots" }
+          if @robots.empty?
+            p { "No robots registered. In your boot script:" }
+            pre { %(require "robot_lab/web"\n\nRobotLab::Web.register(my_robot)) }
+          else
+            ul(class: "robots") do
+              @robots.each do |name|
+                li { a(href: "/robots/#{name}") { name } }
+              end
+            end
+          end
+
+          h2 { "Recent activity" }
+          if @activity.empty?
+            p(class: "muted") { "Nothing yet." }
+          else
+            ul(class: "activity") do
+              @activity.each { |entry| li { plain activity_line(entry) } }
+            end
+          end
+        end
+
+        private
+
+        def activity_line(entry)
+          parts = [entry[:timestamp].strftime("%H:%M:%S"), entry[:type].to_s]
+          details = (entry[:details] || {}).compact
+          parts << details.map { |k, v| "#{k}=#{v}" }.join(" ") unless details.empty?
+          parts.join(" · ")
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/web/components/error_page.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Web
+    module Components
+      # The 404 page body.
+      class ErrorPage < Phlex::HTML
+        def initialize(message:)
+          @message = message
+        end
+
+        def view_template
+          h1 { "Not found" }
+          p { @message }
+          p do
+            a(href: "/", class: "inline-flex items-center gap-1") do
+              render PhlexIcons::Hero::ArrowLeft.new(class: "w-4 h-4")
+              plain "Dashboard"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/web/components/layout.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Web
+    module Components
+      # The HTML document shell: Tailwind (Play CDN) + the shared component
+      # styles, the top nav, and a slot for the page component passed as +content+.
+      class Layout < Phlex::HTML
+        def initialize(csrf:, content:)
+          @csrf = csrf
+          @content = content
+        end
+
+        def view_template
+          doctype
+          html(lang: "en", class: "dark") do
+            head do
+              meta(charset: "utf-8")
+              meta(name: "viewport", content: "width=device-width, initial-scale=1")
+              meta(name: "csrf-token", content: @csrf)
+              title { "robot_lab-web" }
+              # Tailwind via the Play CDN (dev tool — fine for localhost).
+              script(src: "https://cdn.tailwindcss.com")
+              # Styles are Tailwind utilities composed with @apply so the server
+              # components and the SSE client's JS-built nodes share one
+              # definition (the message bubble is rendered by both Message and
+              # chat.js).
+              style(type: "text/tailwindcss") { raw(safe(STYLES)) }
+            end
+            body(class: "bg-zinc-950 text-zinc-200 font-sans text-[15px] leading-relaxed") do
+              header(class: "flex items-center gap-3 px-5 py-3.5 border-b border-zinc-800") do
+                span(class: "flex items-center gap-2 text-violet-400 font-bold tracking-wide") do
+                  render PhlexIcons::Hero::CpuChip.new(class: "w-5 h-5")
+                  plain "robot_lab-web"
+                end
+                a(href: "/", class: "text-indigo-400 no-underline hover:underline") { "Dashboard" }
+              end
+              main(class: "max-w-4xl mx-auto px-5 pt-6 pb-16") { render @content }
+            end
+          end
+        end
+
+        STYLES = <<~CSS
+          @layer base {
+            html { color-scheme: dark; }
+            a    { @apply text-indigo-400 no-underline hover:underline; }
+            h1   { @apply text-2xl font-semibold; }
+            h2   { @apply text-xl font-semibold mt-8 mb-2; }
+            pre  { @apply bg-zinc-900 border border-zinc-800 rounded-md p-3 text-sm overflow-x-auto; }
+            input[type=text] { @apply flex-1 rounded-lg border border-zinc-700 bg-zinc-900 text-zinc-200 px-3.5 py-2.5 outline-none focus:border-indigo-500; }
+            button { @apply rounded-lg bg-indigo-500 text-zinc-950 font-semibold px-4 py-2.5 cursor-pointer; }
+            button:disabled { @apply opacity-50 cursor-default; }
+          }
+          @layer components {
+            .robots   { @apply list-none p-0; }
+            .robots li { @apply mb-2 rounded-lg border border-zinc-800 bg-zinc-900 px-3.5 py-2.5; }
+            .activity { @apply list-none p-0; }
+            .activity li { @apply py-1.5 border-b border-zinc-800/70 text-[13px] text-zinc-400; }
+            .muted    { @apply text-zinc-500; }
+            .transcript { @apply flex flex-col gap-2.5 min-h-[240px] py-2; }
+            .composer { @apply flex gap-2 sticky bottom-0 bg-zinc-950 py-3; }
+            .msg { @apply max-w-[92%] whitespace-pre-wrap break-words rounded-xl border border-zinc-800 px-3.5 py-2.5; }
+            .msg.user { @apply self-end bg-indigo-950/50 border-indigo-800/60; }
+            .msg.robot { @apply self-start bg-emerald-950/40 border-emerald-900/60; }
+            .msg.tool_call, .msg.tool_result { @apply self-start bg-zinc-900 text-zinc-300 text-[13px] font-mono; }
+            .msg.error { @apply self-start bg-rose-950/50 border-rose-900/60 text-rose-200; }
+            .msg .role { @apply text-[11px] uppercase tracking-wider text-zinc-500 mb-1; }
+          }
+        CSS
+      end
+    end
+  end
+end

data/lib/robot_lab/web/components/message.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Web
+    module Components
+      # One transcript message. Used server-side for the non-streaming /chat
+      # fallback; the SSE client builds the same markup (same classes) in JS.
+      class Message < Phlex::HTML
+        def initialize(event:)
+          @event = event
+        end
+
+        def view_template
+          div(class: "msg #{@event.role}") do
+            div(class: "role") { plain role_header }
+            plain body_text
+          end
+        end
+
+        private
+
+        def role_header
+          @event.robot_name ? "#{@event.role} · #{@event.robot_name}" : @event.role.to_s
+        end
+
+        def body_text
+          c = @event.content
+          case @event.role
+          when :tool_call
+            "#{@event.tool_name}(#{c[:args].to_json})"
+          when :tool_result
+            c[:error] ? "#{@event.tool_name} → error: #{c[:error]}" : "#{@event.tool_name} → #{c[:result]}"
+          when :error
+            @event.error_message.to_s
+          else
+            @event.text.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/web/event.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'json'
+require 'securerandom'
+
+module RobotLab
+  module Web
+    # Frontend-neutral, immutable value object for a single step in a robot run.
+    #
+    # One Event model backs both the persisted transcript and the live SSE
+    # stream — serialize with #to_h, rebuild with .from_h. Role validation is
+    # kept strict so a bad role fails fast rather than rendering blank.
+    #
+    # Roles:
+    #   :user        — text the human sent
+    #   :delta       — one streamed token/content delta (content is the text fragment)
+    #   :robot       — the robot's final reply (content is the full final text)
+    #   :tool_call   — a tool invocation (content: { name:, args: })
+    #   :tool_result — a tool's return (content: { name:, result:/error: })
+    #   :error       — the run raised (content: { class:, message: })
+    Event = Struct.new(:role, :content, :robot_name, :timestamp, :event_id, keyword_init: true) do
+      ROLES = %i[user delta robot tool_call tool_result error].freeze # rubocop:disable Lint/ConstantDefinitionInBlock
+
+      def initialize(role:, content:, robot_name: nil, timestamp: nil, event_id: nil)
+        role = role.to_sym
+        raise ArgumentError, "invalid role: #{role.inspect} (expected one of #{ROLES.inspect})" unless ROLES.include?(role)
+
+        super(
+          role: role,
+          content: deep_freeze(content),
+          robot_name: robot_name,
+          timestamp: timestamp || Time.now.utc,
+          event_id: event_id || SecureRandom.uuid
+        )
+        freeze
+      end
+
+      # --- Convenience readers so callers never reach into the content hash ---
+
+      def tool_name
+        content.is_a?(Hash) ? (content[:name] || content['name']) : nil
+      end
+
+      def error?
+        role == :error
+      end
+
+      def error_message
+        return nil unless error?
+
+        content.is_a?(Hash) ? (content[:message] || content['message']) : content.to_s
+      end
+
+      # The display text for this event, whatever its role.
+      def text
+        return content unless content.is_a?(Hash)
+
+        content[:result] || content[:message] || content[:args] || content
+      end
+
+      # --- Serialization (round-trips through JSON for SSE + storage) ---
+
+      def to_h
+        {
+          role: role,
+          content: content,
+          robot_name: robot_name,
+          timestamp: timestamp.iso8601(3),
+          event_id: event_id
+        }
+      end
+
+      def self.from_h(hash)
+        fetch = ->(key) { hash.key?(key) ? hash[key] : hash[key.to_s] }
+        ts = fetch.call(:timestamp)
+        new(
+          role: fetch.call(:role)&.to_sym,
+          content: fetch.call(:content),
+          robot_name: fetch.call(:robot_name),
+          timestamp: ts ? Time.iso8601(ts) : Time.now.utc,
+          event_id: fetch.call(:event_id)
+        )
+      rescue ArgumentError
+        nil
+      end
+
+      private
+
+      def deep_freeze(obj)
+        case obj
+        when Hash
+          obj.each_value { |v| deep_freeze(v) }
+          obj.freeze
+        when Array
+          obj.each { |v| deep_freeze(v) }
+          obj.freeze
+        when String
+          obj.freeze
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/web/event_sink.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Web
+    # The bridge between robot_lab's synchronous hook dispatch and a consumer
+    # (an SSE stream, a collecting array, anything responding to #call).
+    #
+    # robot_lab hooks are class-level singletons, so there is no instance on
+    # which to hang a per-connection callback. We instead stash the consumer in
+    # a thread-local for the duration of a run. Because Robot#run dispatches its
+    # hooks synchronously on the calling thread, the StreamHook sees the right
+    # sink. (Caveat: a robot that executes tools on other threads/Ractors would
+    # not propagate this — fine for the core synchronous path.)
+    #
+    # In effect this gives a robot run an `on_event:` callback without changing
+    # robot_lab's API.
+    module EventSink
+      KEY = :robot_lab_web_event_sink
+
+      module_function
+
+      # Run the block with +sink+ (any callable taking an Event) installed as
+      # the current consumer. Restores the previous sink afterward.
+      def capture(sink)
+        previous = Thread.current[KEY]
+        Thread.current[KEY] = sink
+        yield
+      ensure
+        Thread.current[KEY] = previous
+      end
+
+      def current
+        Thread.current[KEY]
+      end
+
+      # Deliver an Event to the current sink (if any). Never raises into the
+      # run — a broken consumer must not break the robot.
+      def emit(event)
+        sink = current
+        sink&.call(event)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/robot_lab/web/registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Web
+    # In-memory registry of the robots the web UI can drive, keyed by name.
+    # The host app registers robots at boot; the Sinatra app reads from here.
+    module Registry
+      module_function
+
+      def store
+        @store ||= {}
+      end
+
+      # Register a robot (anything responding to #run and #name).
+      def register(robot, name: nil)
+        key = (name || robot.name).to_s
+        store[key] = robot
+        key
+      end
+
+      def fetch(name)
+        store[name.to_s]
+      end
+
+      def names
+        store.keys.sort
+      end
+
+      def all
+        store.values
+      end
+
+      def clear
+        store.clear
+      end
+    end
+  end
+end

data/lib/robot_lab/web/stream_hook.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'event'
+require_relative 'event_sink'
+require_relative 'activity_log'
+
+module RobotLab
+  module Web
+    # Taps robot_lab's hook system and turns each lifecycle moment into a
+    # RobotLab::Web::Event, delivered to the current EventSink and recorded in
+    # the ActivityLog. This is the producer half of the `on_event -> SSE`
+    # bridge that drives the browser console.
+    #
+    # Register per-run so it only fires for web-driven runs:
+    #   robot.run(message, hooks: [RobotLab::Web::StreamHook])
+    # ...inside an EventSink.capture { } block.
+    class StreamHook < RobotLab::Hook
+      self.namespace = :web_stream
+
+      class << self
+        def before_run(ctx)
+          emit(ctx, role: :user, content: ctx.request.to_s)
+        end
+
+        def after_run(ctx)
+          if ctx.error
+            emit_error(ctx, ctx.error)
+          else
+            emit(ctx, role: :robot, content: final_text(ctx.response))
+          end
+        end
+
+        def before_tool_call(ctx)
+          emit(ctx, role: :tool_call, content: { name: ctx.tool_name, args: ctx.tool_args })
+        end
+
+        def after_tool_call(ctx)
+          content =
+            if ctx.tool_error
+              { name: ctx.tool_name, error: ctx.tool_error.message }
+            else
+              { name: ctx.tool_name, result: ctx.tool_result }
+            end
+          emit(ctx, role: :tool_result, content: content)
+        end
+
+        def on_error(ctx)
+          emit_error(ctx, ctx.error)
+        end
+
+        private
+
+        def emit(ctx, role:, content:)
+          event = Event.new(role: role, content: content, robot_name: robot_name(ctx))
+          EventSink.emit(event)
+          ActivityLog.safe_log(role, robot: event.robot_name, tool: event.tool_name)
+          event
+        end
+
+        def emit_error(ctx, error)
+          emit(ctx, role: :error, content: { class: error.class.name, message: error.message })
+        end
+
+        def robot_name(ctx)
+          ctx.respond_to?(:robot) && ctx.robot ? ctx.robot.name : nil
+        end
+
+        def final_text(response)
+          return response.reply if response.respond_to?(:reply)
+          return response.last_text_content if response.respond_to?(:last_text_content)
+
+          response.to_s
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/web/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Web
+    VERSION = "0.2.6"
+  end
+end

data/lib/robot_lab/web.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'web/version'
+
+# Core (Sinatra-free) surface of robot_lab-web. Requiring this gives you the
+# event model, activity log, sink, registry, and — when robot_lab is loaded —
+# the StreamHook. The Sinatra app and its heavy deps (sinatra, falcon, phlex) are
+# opt-in: `require "robot_lab/web/app"`, which keeps the web stack off the core
+# load path.
+require_relative 'web/event'
+require_relative 'web/activity_log'
+require_relative 'web/event_sink'
+require_relative 'web/registry'
+
+# robot_lab is a hard dependency: StreamHook subclasses RobotLab::Hook. Require
+# it here so load order never matters (the exe/config.ru may require this file
+# before a user boot script gets to require "robot_lab").
+require 'robot_lab'
+require_relative 'web/stream_hook'
+
+module RobotLab
+  # Browser front end for a robot_lab project: stream a robot's run to a web
+  # page over Server-Sent Events (an on_event -> SSE bridge, an immutable Event
+  # value object, an in-memory ActivityLog, and a hardened dev-tool security
+  # posture).
+  module Web
+    class Error < StandardError; end
+
+    module_function
+
+    # Register a robot the web UI can drive. Returns the string key.
+    #
+    #   RobotLab::Web.register(my_robot)
+    #   RobotLab::Web.register(my_robot, name: "support")
+    def register(robot, name: nil)
+      Registry.register(robot, name: name)
+    end
+
+    # Run +robot+ against +message+, delivering each lifecycle Event to +sink+
+    # (a callable taking an Event) as it happens, and returning the robot's
+    # RobotResult. This is the one call the web routes wrap; it is also the
+    # cleanest way to consume the stream from plain Ruby or a test.
+    #
+    # Two layers of events arrive at the sink:
+    #   * StreamHook turns robot_lab hook moments into :user / :tool_call /
+    #     :tool_result / :robot / :error events.
+    #   * the streaming block below turns each RubyLLM content chunk into a
+    #     :delta event, so the reply can be rendered token by token. (A model or
+    #     run that doesn't stream simply produces no deltas — the final :robot
+    #     event still carries the whole reply.)
+    #
+    #   events = []
+    #   RobotLab::Web.run(robot, "hello") { |event| events << event }
+    def run(robot, message, sink = nil, &block)
+      sink ||= block
+      name = robot.respond_to?(:name) ? robot.name : nil
+      EventSink.capture(sink) do
+        robot.run(message, hooks: [StreamHook]) do |chunk|
+          delta = chunk.respond_to?(:content) ? chunk.content : chunk.to_s
+          next if delta.nil? || delta.empty?
+
+          # Emit straight to the sink — deltas bypass the ActivityLog so token
+          # spam never floods the dashboard's recent-activity feed.
+          EventSink.emit(Event.new(role: :delta, content: delta, robot_name: name))
+        end
+      end
+    end
+
+    # Boot the Sinatra app. Requires the opt-in web stack on first call.
+    #
+    #   RobotLab::Web.app  # => RobotLab::Web::App (a Rack app)
+    def app
+      require_relative 'web/app'
+      App
+    end
+  end
+end