robot_lab-web 0.2.6

data/docs/how_it_works.md

@@ -0,0 +1,138 @@
+# How It Works
+
+## Core vs. Opt-In Web Stack
+
+`robot_lab-web` is split into two load paths:
+
+- **`require "robot_lab/web"`** — the core, Sinatra-free surface: `Event`, `ActivityLog`, `EventSink`, `Registry`, and (since `robot_lab` is a hard dependency, required directly by this file so load order never matters) `StreamHook`. No Sinatra, Falcon, or Phlex touched at all — this is everything `RobotLab::Web.run`/`.register` need, and everything a test or a custom front end needs too.
+- **`require "robot_lab/web/app"`** (or simply call `RobotLab::Web.app`, which requires it lazily on first use) — pulls in Sinatra, `phlex-sinatra`, `phlex-icons-hero`, and the bundled `App` class plus its Phlex view components.
+
+This split exists so that consuming the event stream from plain Ruby (a test, a script, an alternate front end) never has to load Sinatra/Falcon/Phlex at all — those are only paid for when you actually want the bundled console.
+
+## The Event Model
+
+`RobotLab::Web::Event` is a frontend-neutral, **immutable** value object for a single step in a robot run — the one model backing both the persisted (in-memory) activity log and the live SSE stream. It's a `Struct` (keyword-init) that deep-freezes its `content` on construction (recursively, through nested Hashes/Arrays/Strings) and freezes itself, so an `Event` handed to a sink can never be mutated by that sink afterward.
+
+| Role | `content` shape | Meaning |
+|---|---|---|
+| `:user` | `String` | Text the human sent |
+| `:delta` | `String` | One streamed token/content fragment |
+| `:robot` | `String` | The robot's final reply (the whole text, not a fragment) |
+| `:tool_call` | `{name:, args:}` | A tool invocation |
+| `:tool_result` | `{name:, result:}` or `{name:, error:}` | A tool's return (or its failure) |
+| `:error` | `{class:, message:}` | The run itself raised |
+
+Role validation is strict — `Event.new(role: :bogus, ...)` raises `ArgumentError` immediately rather than silently rendering a blank or malformed bubble later. Construction also stamps a UTC `timestamp` and a random `event_id` (`SecureRandom.uuid`) when not given explicitly.
+
+Convenience readers mean callers never have to reach into the `content` hash directly: `#tool_name` (works for both `:tool_call` and `:tool_result`), `#error?`, `#error_message`, and `#text` — a role-agnostic "what should I display" reader that unwraps `content[:result]`/`content[:message]`/`content[:args]` for hash-shaped content, or returns `content` itself otherwise.
+
+`#to_h`/`.from_h` round-trip an `Event` through JSON (used both for SSE frames and any future persistence) — `timestamp` serializes as ISO 8601 with millisecond precision; `from_h` accepts either symbol or string keys (`hash.key?(key) ? hash[key] : hash[key.to_s]`) so it can rebuild an `Event` from a hash decoded from JSON (string keys) just as easily as one built in Ruby (symbol keys), and returns `nil` rather than raising if the role can't be validated.
+
+## The Hook-to-Sink Bridge
+
+Two pieces work together to turn a synchronous `robot.run` call into a live event stream, without adding any new API surface to `robot_lab` core itself:
+
+### `EventSink` — a thread-local mailbox
+
+`robot_lab` hooks are **class-level singletons** — there's no hook instance to hang a per-connection callback on. `EventSink` works around this by stashing the current consumer (any object responding to `#call`) in a `Thread.current` slot for the duration of one run:
+
+```ruby
+EventSink.capture(sink) { robot.run(message, hooks: [StreamHook]) { |chunk| ... } }
+```
+
+Because `Robot#run` dispatches its hooks **synchronously on the calling thread**, `StreamHook` (running inside that same call) sees exactly the right sink via `EventSink.current`. `EventSink.emit(event)` delivers to it and swallows any `StandardError` the sink itself raises — a broken consumer (a dead SSE connection, a bug in a custom sink) must never break the robot run it's observing.
+
+**Caveat, stated directly in the source:** a robot that executes tools on other threads or via Ractors would not propagate this thread-local — fine for `robot_lab`'s core synchronous tool-call path, but worth knowing if you're pairing this with `robot_lab-ractor` or similar.
+
+### `StreamHook` — the producer
+
+A `RobotLab::Hook` subclass (`namespace = :web_stream`) that taps every lifecycle moment `robot_lab`'s hook system exposes and turns it into an `Event`, delivered to the current `EventSink` and also recorded in `ActivityLog` (see below):
+
+| Hook callback | Emits |
+|---|---|
+| `before_run` | `:user` — the incoming request text |
+| `after_run` (success) | `:robot` — the final reply text (`ctx.response.reply`, falling back to `#last_text_content`, then plain `#to_s`) |
+| `after_run` (error) | `:error` |
+| `before_tool_call` | `:tool_call` |
+| `after_tool_call` | `:tool_result` (success or error shape, depending on `ctx.tool_error`) |
+| `on_error` | `:error` |
+
+Registered **per-run**, not globally (`robot.run(message, hooks: [RobotLab::Web::StreamHook])`), so it only fires for web-driven runs — a robot used elsewhere in your app, outside the console, is completely unaffected.
+
+### `RobotLab::Web.run` — the one call that ties it together
+
+```ruby
+def run(robot, message, sink = nil, &block)
+  sink ||= block
+  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?
+      EventSink.emit(Event.new(role: :delta, content: delta, robot_name: name))
+    end
+  end
+end
+```
+
+This is the single call both Sinatra routes wrap, and the cleanest way to consume the stream from plain Ruby or a test. **Two independent layers of events reach the sink:**
+
+1. `StreamHook`, translating `robot_lab` hook moments into `:user`/`:tool_call`/`:tool_result`/`:robot`/`:error` events, and
+2. the streaming block passed to `robot.run` itself, translating each RubyLLM content chunk into a `:delta` event.
+
+A model or run that doesn't stream token-by-token simply produces no `:delta` events at all — the final `:robot` event still carries the complete reply either way, so nothing is lost, only the incremental rendering.
+
+**Deltas deliberately bypass `ActivityLog`** — `StreamHook`'s `emit` helper logs to the activity feed on every call, but the delta block above calls `EventSink.emit` directly, skipping that logging so token-by-token spam never floods the dashboard's recent-activity feed with hundreds of entries per run.
+
+## `ActivityLog`
+
+A thread-safe, bounded (`MAX_EVENTS` = 50) in-memory ring buffer backing the dashboard's "recent activity" feed — a process-wide singleton (`ActivityLog.instance`), not per-connection. `.safe_log` is the cardinal rule enforced everywhere this is called from instrumentation paths: swallow any error, because **recording that something happened must never be able to break the thing that happened**.
+
+This is intentionally separate from the SSE event stream itself — the activity log is a lightweight, best-effort summary (`role`, `robot`, `tool` — see `StreamHook#emit`'s `ActivityLog.safe_log(role, robot: ..., tool: ...)` call) for the dashboard's overview, not the full transcript; the full transcript only ever exists as the live SSE stream (or whatever a custom sink chooses to persist).
+
+## `Registry`
+
+A plain in-memory `Hash`, keyed by robot name (string) — the host app registers robots at boot (`RobotLab::Web.register`), and the Sinatra app reads from it (`Registry.fetch`/`.names`/`.all`) to know what it can list and drive. No persistence beyond the process's own memory — restarting the console clears the registry, and it's rebuilt entirely by whatever boot file ran at start.
+
+## The SSE Wire Protocol
+
+`POST /robots/:name/stream` sets `content_type 'text/event-stream'` and streams frames as they happen, using Sinatra's `stream do |out| ... end`:
+
+```ruby
+write_sse = ->(type, data) { out << "event: #{type}\ndata: #{JSON.generate(data)}\n\n" }
+```
+
+Three frame types:
+
+| `event:` | `data:` payload | When |
+|---|---|---|
+| `message` | `event.to_h` (a full `Event`, JSON-encoded) | Once per `Event` the run produces — every `:user`/`:delta`/`:tool_call`/`:tool_result`/`:robot`/`:error` |
+| `done` | `{reply: <final text>}` | Once, after the run completes successfully |
+| `error` | `{message: <text>}` | Once, if the request had no `message` param, or if the run itself raised |
+
+**Why this isn't a plain browser `EventSource`:** the stream route is CSRF-protected (see [Security](security.md#csrf-protection)), and `EventSource` is GET-only and cannot send custom headers or a request body — there's no way to attach a CSRF token to it. The bundled `Chat` component's client-side JS instead uses `fetch()` with a `ReadableStream` reader, manually parsing the same `event:`/`data:` frame format `EventSource` would have handled natively:
+
+```js
+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();
+// ...decode chunks, split on "\n\n" into frames, parse "event:"/"data:" lines...
+```
+
+The parsing loop buffers incoming bytes, splits on blank lines (`\n\n`, the SSE frame delimiter) keeping the last, possibly-incomplete fragment in the buffer for the next read, and for each complete frame extracts the `event:` and `data:` lines exactly the way a native `EventSource` would internally.
+
+## Token-Delta Rendering, Client-Side
+
+The chat page's JS keeps a single "currently streaming" bubble reference (`streaming`) while `:delta` events arrive, appending each fragment's text (`streaming.textContent += ev.content`) so the reply grows token-by-token in place. When the terminal `:robot` event arrives, it replaces the accumulated text with the final authoritative string (`streaming.textContent = ev.content`) and clears the `streaming` reference — the delta-built text and the final `:robot` text should be identical in the normal case, but the final event is treated as the source of truth. `:user` events are skipped entirely on render — the client already rendered the user's own message optimistically, immediately on form submit, before the request even went out.
+
+## Two Ways to Render the Same Transcript
+
+The same `Event` → HTML mapping exists in two places, by necessity: `Components::Message` (Phlex, server-side — used by the non-streaming `/chat` fallback endpoint) and the inline JS in `Components::Chat::CLIENT_JS` (client-side — used by the streaming `/stream` endpoint's `fetch()` client). They're kept in sync intentionally (same CSS classes — `.msg`, `.msg.user`, `.msg.tool_call`, etc. — defined once in `Layout::STYLES` and shared by both renderers) but are genuinely two separate implementations, since the streaming path never touches the server-side Phlex renderer for the events it's actively streaming — only the non-streaming fallback does.
+
+The non-streaming `/robots/:name/chat` endpoint explicitly filters out `:delta` events before rendering (`events.reject { |event| event.role == :delta }`) — since the final `:robot` event already carries the complete reply, showing the deltas too would duplicate the same text piecemeal-then-whole in a static (non-incremental) render.
+
+## Falcon as the Application Server
+
+`exe/robot_lab-web` builds a single `Falcon::Server` (not Puma) and calls `#run` at the top level, which blocks on the accept loop until interrupted. Falcon's async/fiber reactor gives cheap fiber-per-connection concurrency in one process — the right fit for a console serving multiple long-lived SSE streams at once, since each connection can sit open (mid-stream) for as long as a robot run takes without tying up an OS thread the way a thread-per-connection server would. `config.ru` itself stays server-agnostic — nothing in the Sinatra `App` class requires Falcon specifically; any Rack server can run it, just without that same cheap concurrency model for long-lived connections.

data/docs/index.md

@@ -0,0 +1,59 @@
+# robot_lab-web
+
+A Rails-free **web console for [robot_lab](https://github.com/MadBomber/robot_lab)**: register your robots, chat with them from the browser, and watch each lifecycle event — tool calls, tool results, the final reply, errors — **stream in real time** over Server-Sent Events.
+
+It's the standalone counterpart to [`robot_lab-rails`](https://github.com/MadBomber/robot_lab-rails): one event stream, a Sinatra + HTMX front end, no Turbo and no Rails required.
+
+```ruby
+# my_robots.rb
+require "robot_lab"
+require "robot_lab/web"
+
+assistant = RobotLab.build(name: "assistant", system_prompt: "You are concise.")
+RobotLab::Web.register(assistant)
+```
+
+```sh
+robot_lab-web my_robots.rb   # http://127.0.0.1:9292 — pick a robot, start chatting
+```
+
+!!! warning "Developer tool — unauthenticated by default"
+    The console has no login. Run it on localhost or a trusted private network. It ships sensible hardening (CSRF with a constant-time compare, a hashed and persisted session secret, `httponly`/`SameSite` cookies, a production boot guard) but is **not** meant to face untrusted users. See [Security](security.md) for the full posture and its limits.
+
+## How It Fits Together
+
+```
+browser ──POST /robots/:name/stream──▶ Sinatra App
+                                         └─ RobotLab::Web.run(robot, msg) { |event| write_sse }
+                                              └─ robot.run(msg, hooks: [StreamHook])
+                                                   └─ StreamHook ─emits─▶ EventSink ─▶ SSE frames
+```
+
+`robot_lab-web` registers a per-run hook (`RobotLab::Web::StreamHook`) on `robot_lab`'s own hook system. As a robot runs, the hook turns each moment into an immutable `RobotLab::Web::Event` and pushes it to whatever sink is currently listening — an SSE stream for the browser, or a plain array in a test. This is `robot_lab`'s native equivalent of an `on_event:` callback, built entirely out of existing hook infrastructure rather than a new API on `Robot` itself.
+
+## Navigation
+
+- [Getting Started](getting_started.md) — installation, writing a boot file, launching the console, the four HTTP endpoints
+- [How It Works](how_it_works.md) — the event model, the hook-to-sink bridge, the SSE wire protocol and its browser-side client, token-delta streaming, the opt-in core/Sinatra split
+- [API Reference](api_reference.md) — every public class and method
+- [Security](security.md) — the full hardening posture (CSRF, session secret, cookies, host authorization, production guard) and exactly what it does and doesn't protect against
+
+## At a Glance
+
+| | |
+|---|---|
+| **Server** | [Falcon](https://github.com/socketry/falcon) (async/fiber reactor — the right fit for long-lived SSE streams); `config.ru` itself is server-agnostic |
+| **Views** | [Phlex](https://www.phlex.fun/) components, rendered via `phlex-sinatra`, styled with Tailwind (Play CDN), icons from `phlex-icons-hero` |
+| **Front end** | Vanilla JS `fetch()` streaming client (not `EventSource` — the stream route is CSRF-protected, and `EventSource` can't send custom headers) plus an HTMX-compatible non-streaming fallback |
+| **Core dependency** | `require "robot_lab/web"` alone gets you the event model, activity log, sink, and registry — no Sinatra/Falcon/Phlex loaded |
+| **Opt-in web stack** | `require "robot_lab/web/app"` (or call `RobotLab::Web.app`) pulls in Sinatra, Falcon, and Phlex |
+| **Endpoints** | `GET /`, `GET /robots/:name`, `POST /robots/:name/stream` (SSE), `POST /robots/:name/chat` (non-streaming HTMX fallback) |
+| **Hook used** | `RobotLab::Web::StreamHook`, registered per-run (`hooks: [StreamHook]`), not globally |
+
+## Links
+
+- [RobotLab Core](https://github.com/MadBomber/robot_lab)
+- [robot_lab-rails](https://github.com/MadBomber/robot_lab-rails) — the Rails/Turbo counterpart to this gem
+- [RubyGems](https://rubygems.org/gems/robot_lab-web)
+- [GitHub](https://github.com/MadBomber/robot_lab-web)
+- [Changelog](https://github.com/MadBomber/robot_lab-web/blob/main/CHANGELOG.md)

data/docs/security.md

@@ -0,0 +1,75 @@
+# Security
+
+## The Posture, Stated Plainly
+
+`robot_lab-web` is a **developer tool**, unauthenticated by default. There is no login, no user model, no access control of any kind on any route. Everything below hardens specific, real attack surfaces (CSRF, session-cookie theft, Host-header tricks, an accidentally-insecure production boot), but **none of it adds authentication**. Run this on `localhost` or a network you already trust; do not expose it to the public internet or to untrusted users on a shared network, regardless of how hardened the pieces below are individually.
+
+## CSRF Protection
+
+Every non-safe request (anything but `GET`/`HEAD`/`OPTIONS`) must carry a valid CSRF token, checked with a **constant-time comparison** (`Rack::Utils.secure_compare`) specifically to avoid a timing side-channel that could otherwise leak the correct token one byte at a time:
+
+```ruby
+before do
+  session[:csrf] ||= SecureRandom.hex(32)
+  next if CSRF_SAFE_METHODS.include?(request.request_method)
+
+  provided = params['authenticity_token'] || request.env['HTTP_X_CSRF_TOKEN']
+  halt 403, 'Forbidden: invalid CSRF token' unless provided && Rack::Utils.secure_compare(provided, session[:csrf])
+end
+```
+
+The token is accepted from either a form field (`authenticity_token`) or a request header (`X-CSRF-Token`) — the latter is what the streaming chat client actually uses, since its request body is a URL-encoded `message=...` string, not a form submission carrying a hidden field. The page embeds the token in a `<meta name="csrf-token">` tag; the client JS reads it from there.
+
+**This is also why the streaming route can't be a plain browser `EventSource`** — `EventSource` is GET-only and can't attach custom headers, so there'd be no way to present a CSRF token on that connection at all. See [How It Works — The SSE Wire Protocol](how_it_works.md#the-sse-wire-protocol) for the `fetch()`-based client this constraint leads to instead.
+
+## Session Secret Persistence
+
+Sinatra's encrypted cookie session store needs a stable secret — if the secret changes between requests, every existing session cookie becomes invalid (Sinatra's own "HMAC is invalid" error) and users get silently logged out (or, here, lose their CSRF token) on every restart. `App.session_secret_source` resolves the secret in priority order:
+
+1. `ENV['SESSION_SECRET']`, if set
+2. A **persisted** per-installation random secret, generated once and written to `~/.config/robot_lab/web_session_secret` (mode `0600`) — read back on every subsequent boot instead of regenerating
+
+```ruby
+def self.persisted_dev_secret
+  path = File.join(Dir.home, '.config', 'robot_lab', 'web_session_secret')
+  existing = File.read(path).strip if File.exist?(path)
+  return existing if existing && !existing.empty?
+
+  SecureRandom.hex(64).tap { |secret| File.write(path, secret); File.chmod(0o600, path) }
+end
+```
+
+The resolved secret is then **hashed** (`OpenSSL::Digest::SHA256.hexdigest(...)`) before being handed to Sinatra as `session_secret` — Sinatra's encrypted-cookie store errors on a secret that's too short or an odd length, and hashing to a fixed 64-hex-char digest makes *any* input value (a short `SESSION_SECRET`, an oddly-sized one) work deterministically, without validating the input's shape yourself.
+
+## Cookie Flags
+
+```ruby
+set :sessions, httponly: true, same_site: :lax, secure: production?
+```
+
+`httponly: true` — the session cookie is inaccessible to JavaScript (mitigates cookie theft via an XSS bug). `same_site: :lax` — the cookie isn't sent on most cross-site requests (mitigates CSRF further, on top of the explicit token check above). `secure: production?` — the cookie is marked HTTPS-only when running in a Sinatra `production` environment; left off in development, where a local Falcon instance typically isn't behind TLS at all.
+
+## Production Boot Guard
+
+```ruby
+configure :production do
+  unless ENV['SESSION_SECRET']
+    raise 'SESSION_SECRET must be set in production; a per-process random ' \
+          'fallback breaks sessions and CSRF across restarts and workers.'
+  end
+end
+```
+
+In a Sinatra `production` environment specifically, the persisted-random-secret fallback is refused outright — the app raises at boot rather than starting with a secret that (in a real production deployment, likely running multiple worker processes) would differ across those workers and break sessions/CSRF unpredictably between them. This forces an explicit `SESSION_SECRET` in that one environment; development and test both still get the persisted-file fallback.
+
+## Host Authorization
+
+```ruby
+set :host_authorization, { permitted_hosts: [] }
+```
+
+Sinatra 4 (via `rack-protection`) enables Host-header authorization by default, 403-ing any request whose `Host` header isn't on an explicit allowlist — a real protection against DNS-rebinding-style attacks in a typical web app. This console explicitly disables that check (`permitted_hosts: []` means "permit all") because, as a developer tool, it's reached via whatever host the operator chooses to bind (`localhost`, a LAN IP, a hostname on a private network) and there's no fixed "correct" host to allowlist ahead of time. This is a deliberate trade-off specific to this tool's use case, not an oversight — but it does mean Host-header-based attacks that this default would otherwise have blocked are back in play, which is one more reason this console belongs on a trusted network only.
+
+## What This Doesn't Protect Against
+
+To be explicit about the boundary: none of the above prevents **any** visitor who can reach the console's port from listing robots, reading recent activity, or driving a full chat run against any registered robot (including whatever tools that robot has access to). If a robot registered here has a tool that can read files, run shell commands, or call external APIs with real credentials, anyone who can reach this console can exercise all of that. Treat the console's network reachability itself as the actual access-control boundary, not anything documented above.

data/examples/boot.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Example boot file for robot_lab-web.
+#
+#   robot_lab-web examples/boot.rb
+#   # or
+#   ROBOT_LAB_WEB_BOOT=examples/boot.rb rackup
+#
+# Build whatever robots you want and register each one. The web console reads
+# the registry to list and drive them. Actually running a robot requires the
+# provider API key for its model (e.g. ANTHROPIC_API_KEY).
+
+require "robot_lab"
+require "robot_lab/web"
+
+assistant = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are a concise, friendly assistant."
+)
+
+RobotLab::Web.register(assistant)
+
+# Register as many as you like:
+# RobotLab::Web.register(RobotLab.build(name: "support", template: :support))

data/exe/robot_lab-web

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Launch the robot_lab-web console with Falcon (async/fiber reactor — the right
+# fit for the long-lived SSE streams this console serves).
+#
+#   robot_lab-web [--port 9292] [--host 127.0.0.1] [boot_file.rb]
+#
+# boot_file.rb (or $ROBOT_LAB_WEB_BOOT) should require robot_lab, build your
+# robots, and RobotLab::Web.register each one.
+
+# Set up the bundle when run from a source checkout (a Gemfile sits beside us),
+# so the gem's own lib and its dependencies — including the local robot_lab path
+# dependency in development — resolve. Run this from the gem directory (or via
+# `bundle exec`); the loki bundler plugin resolves Gemfile.local relative to the
+# working directory. An installed gem has no Gemfile here and uses RubyGems.
+require 'bundler/setup' if File.exist?(File.expand_path('../Gemfile', __dir__))
+
+require 'optparse'
+require 'robot_lab/web'
+
+options = { port: 9292, host: '127.0.0.1' }
+OptionParser.new do |o|
+  o.banner = 'Usage: robot_lab-web [options] [boot_file.rb]'
+  o.on('-p', '--port PORT', Integer, 'Port (default 9292)') { |v| options[:port] = v }
+  o.on('-h', '--host HOST', 'Bind host (default 127.0.0.1)') { |v| options[:host] = v }
+end.parse!
+
+boot = ARGV.shift || ENV.fetch('ROBOT_LAB_WEB_BOOT', nil)
+require File.expand_path(boot) if boot && File.exist?(boot)
+
+require 'async'
+require 'async/http/endpoint'
+require 'falcon/server'
+
+rack_app = RobotLab::Web.app
+endpoint = Async::HTTP::Endpoint.parse("http://#{options[:host]}:#{options[:port]}")
+
+warn "robot_lab-web on http://#{options[:host]}:#{options[:port]} (Falcon) " \
+     "(#{RobotLab::Web::Registry.names.size} robot(s) registered)"
+
+# A single fiber reactor: one process with cheap fiber-per-connection
+# concurrency, so the dashboard's in-memory state (Registry, ActivityLog) stays
+# consistent while many SSE streams run at once. Ctrl-C to stop.
+#
+# Server#run wraps itself in `Async { ... }` and blocks on the accept loop, so
+# calling it at the top level starts the reactor and serves until interrupted.
+server = Falcon::Server.new(Falcon::Server.middleware(rack_app), endpoint)
+server.run

data/lib/robot_lab/web/activity_log.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module RobotLab
+  module Web
+    # Thread-safe, bounded, in-memory ring buffer for a dashboard "recent
+    # activity" feed.
+    #
+    # The cardinal rule, enforced by .safe_log: instrumentation must never
+    # break the request that triggered it.
+    class ActivityLog
+      MAX_EVENTS = 50
+
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        def log(type, details = {})
+          instance.log(type, details)
+        end
+
+        # Record an event, swallowing any error.
+        def safe_log(type, details = {})
+          log(type, details)
+        rescue StandardError
+          nil
+        end
+
+        def recent(limit = 10)
+          instance.recent(limit)
+        end
+
+        def clear
+          instance.clear
+        end
+      end
+
+      def initialize
+        @events = []
+        @mutex = Mutex.new
+      end
+
+      def log(type, details = {})
+        @mutex.synchronize do
+          @events.unshift(type: type.to_sym, details: details, timestamp: Time.now.utc)
+          @events = @events.first(MAX_EVENTS)
+        end
+      end
+
+      def recent(limit = 10)
+        @mutex.synchronize { @events.first(limit) }
+      end
+
+      def clear
+        @mutex.synchronize { @events = [] }
+      end
+    end
+  end
+end

data/lib/robot_lab/web/app.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'securerandom'
+require 'json'
+require 'sinatra/base'
+require 'phlex-sinatra'
+require 'phlex-icons-hero'
+require 'rack/utils'
+
+require_relative '../web'
+require_relative 'components/layout'
+require_relative 'components/dashboard'
+require_relative 'components/chat'
+require_relative 'components/message'
+require_relative 'components/error_page'
+
+module RobotLab
+  module Web
+    # Sinatra console for driving robot_lab robots from the browser and
+    # streaming each run over Server-Sent Events.
+    #
+    # This is a DEVELOPER TOOL, unauthenticated by default — run it on
+    # localhost or a trusted network. The security touches below (CSRF with
+    # constant-time compare, hashed session secret, cookie flags, production
+    # boot guard) harden the surface but do not make it safe to expose publicly.
+    class App < Sinatra::Base
+      # phlex-sinatra registers its `phlex` helper on the classic
+      # Sinatra::Application; a modular Sinatra::Base app must include it.
+      helpers Phlex::Sinatra
+
+      # Stable session secret. Uses SESSION_SECRET when set; otherwise persists a
+      # per-user random secret so it survives restarts. A fresh random secret on
+      # every boot would invalidate existing session cookies ("HMAC is invalid").
+      def self.session_secret_source
+        ENV['SESSION_SECRET'] || persisted_dev_secret
+      end
+
+      def self.persisted_dev_secret
+        path     = File.join(Dir.home, '.config', 'robot_lab', 'web_session_secret')
+        existing = File.read(path).strip if File.exist?(path)
+        return existing if existing && !existing.empty?
+
+        require 'fileutils'
+        FileUtils.mkdir_p(File.dirname(path))
+        SecureRandom.hex(64).tap do |secret|
+          File.write(path, secret)
+          File.chmod(0o600, path)
+        end
+      end
+
+      configure do
+        # Sinatra 4 / rack-protection enable Host authorization by default,
+        # which 403s any Host header not explicitly permitted. This dev tool is
+        # reached via localhost or whatever host the operator binds — permit all.
+        set :host_authorization, { permitted_hosts: [] }
+        set :sessions, httponly: true, same_site: :lax, secure: production?
+
+        # Hash to a 64-hex key — the encrypted-cookie store errors on short/odd
+        # secrets; hashing makes any value work deterministically.
+        set :session_secret, OpenSSL::Digest::SHA256.hexdigest(session_secret_source)
+      end
+
+      configure :production do
+        unless ENV['SESSION_SECRET']
+          raise 'SESSION_SECRET must be set in production; a per-process random ' \
+                'fallback breaks sessions and CSRF across restarts and workers.'
+        end
+      end
+
+      CSRF_SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
+
+      before do
+        session[:csrf] ||= SecureRandom.hex(32)
+        next if CSRF_SAFE_METHODS.include?(request.request_method)
+
+        provided = params['authenticity_token'] || request.env['HTTP_X_CSRF_TOKEN']
+        halt 403, 'Forbidden: invalid CSRF token' unless provided &&
+                                                         Rack::Utils.secure_compare(provided, session[:csrf])
+      end
+
+      helpers do
+        def csrf_token
+          session[:csrf]
+        end
+
+        # Render a page component wrapped in the Layout (HTML doc shell).
+        def page(content)
+          phlex Components::Layout.new(csrf: csrf_token, content: content)
+        end
+
+        def robot_or_not_found(name)
+          Registry.fetch(name) ||
+            halt(404, page(Components::ErrorPage.new(message: "No robot named #{name.inspect}")))
+        end
+
+        # Render one transcript message (Event) to an HTML fragment.
+        def message_html(event)
+          Components::Message.new(event: event).call
+        end
+      end
+
+      # --- Dashboard -------------------------------------------------------
+
+      get '/' do
+        page Components::Dashboard.new(robots: Registry.names, activity: ActivityLog.recent(15))
+      end
+
+      get '/robots/:name' do
+        robot_or_not_found(params[:name])
+        page Components::Chat.new(name: params[:name])
+      end
+
+      # --- Streaming run (SSE) ---------------------------------------------
+      #
+      # Each lifecycle Event is pushed the instant it happens; the run ends with
+      # a `done` frame (or `error`). Consume with fetch() streaming — the route
+      # is CSRF-protected, so EventSource (GET-only, no headers) can't be used.
+      post '/robots/:name/stream' do
+        robot = robot_or_not_found(params[:name])
+        message = params['message'].to_s
+
+        content_type 'text/event-stream'
+        headers 'Cache-Control' => 'no-cache', 'X-Accel-Buffering' => 'no'
+
+        stream do |out|
+          write_sse = ->(type, data) { out << "event: #{type}\ndata: #{JSON.generate(data)}\n\n" }
+
+          if message.empty?
+            write_sse.call('error', { message: "Missing 'message'." })
+          else
+            begin
+              result = RobotLab::Web.run(robot, message) { |event| write_sse.call('message', event.to_h) }
+              write_sse.call('done', { reply: final_text(result) })
+            rescue StandardError => e
+              write_sse.call('error', { message: e.message })
+            end
+          end
+        end
+      end
+
+      # --- Non-streaming fallback (HTMX append) — resilient default -------
+      #
+      # Works without JS streaming: run to completion, collect events, return
+      # the rendered transcript fragments for `hx-swap="beforeend"`.
+      post '/robots/:name/chat' do
+        robot = robot_or_not_found(params[:name])
+        message = params['message'].to_s
+        halt 400, 'Missing message' if message.empty?
+
+        events = []
+        RobotLab::Web.run(robot, message) { |event| events << event }
+        content_type :html
+        # Drop :delta events — the final :robot event already carries the full
+        # reply, so the non-streaming transcript shows it once.
+        events.reject { |event| event.role == :delta }
+              .map { |event| message_html(event) }.join("\n")
+      end
+
+      helpers do
+        def final_text(result)
+          return result.reply if result.respond_to?(:reply)
+          return result.last_text_content if result.respond_to?(:last_text_content)
+
+          result.to_s
+        end
+      end
+    end
+  end
+end