samagotchi 0.2.0

data/lib/samagotchi/web/app.rb

@@ -0,0 +1,1349 @@
+# frozen_string_literal: true
+
+require "cgi/escape" # CGI.escapeHTML; Ruby 4.0 ships only cgi/escape
+require "fileutils"
+require "json"
+require "time"
+require "uri"
+require "rack"
+require "rack/request"
+
+require_relative "../bridge_client"
+require_relative "../bridge/bounded_queue"
+require_relative "../session"
+require_relative "../session_manager"
+require_relative "../session_commands"
+require_relative "../host_registry"
+require_relative "../model_profile"
+require_relative "../project_scope"
+require_relative "../version"
+require_relative "../output_formatter"
+require_relative "../image_store"
+require_relative "../context_note"
+require_relative "../recap_store"
+require_relative "markdown_renderer"
+require_relative "message_parts"
+require_relative "session_summary"
+require_relative "../log"
+
+module Samagotchi
+  module Web
+    # Rack application that serves the Web UI and JSON API.
+    #
+    # This is the single-port control plane for Chi Web. It never constructs
+    # an Engine directly — it talks to SessionManager over the file IPC layer.
+    # Live SSE is proxied from each session's Bridge
+    # (the single live client transport); history for any session — including
+    # dead ones — is served by GET /api/sessions/:id/output from output/ files.
+    class App
+      DEFAULT_HOST = BridgeClient::HOST
+      BRIDGE_WAIT_TIMEOUT = 10.0
+      # An uploaded image may be this big before it is downscaled.
+      MAX_IMAGE_UPLOAD_BYTES = 20 * 1024 * 1024
+      SESSION_ID_RE = /\A[0-9A-Za-z-]{1,64}\z/
+      IMAGE_NAME_RE = /\A[0-9a-f]{16}\.(png|jpe?g|gif|webp)\z/
+      IMAGE_TYPES = { "png" => "image/png", "jpg" => "image/jpeg", "jpeg" => "image/jpeg", "gif" => "image/gif",
+                      "webp" => "image/webp" }.freeze
+      # The cancel reasons a client may give, as the Bridge takes them
+      # (Bridge::CANCEL_REASONS); anything else is sent and echoed as manual.
+      CANCEL_REASONS = %w[manual user ctrl_c].freeze
+
+      # POST /stop waits this long for the worker to let go of the session.
+      STOP_WAIT_SECONDS = 2.0
+
+      # GET /api/events: a `: ping` this often while idle, a queue this deep
+      # per tab (an overflow ends the connection; the reconnect's snapshot
+      # is the recovery), and the loop's longest wait before it looks at
+      # whether the hub or the server is shutting down.
+      EVENTS_HEARTBEAT = 15.0
+      EVENTS_QUEUE = 256
+      # Seconds GET /api/models waits for the hosts' lists before answering
+      # with what it has (the listing goes on and fills the registry's cache).
+      MODELS_WAIT_TIMEOUT = 4.0
+      EVENTS_POLL = 1.0
+
+      # A callable the event loops ask whether the server still runs;
+      # Server.start points it at WEBrick's status once it has the server.
+      attr_writer :server_running
+
+      # @param bridge_wait_timeout [Float] bounded seconds to wait for a
+      #   freshly-spawned worker's bridge before answering POST /api/sessions.
+      # @param turn_view [Boolean] the page's per-turn view (web.turn_view,
+      #   the default); false is the classic row of bubbles; ?view=turn|chat
+      #   overrides it for one page load
+      # @param hub [SessionHub, nil] the session projection GET /api/events
+      #   streams from; without one the route answers 503
+      # @param registry [HostRegistry, nil] the hosts GET /api/models lists
+      #   (built from the config on first use)
+      # @param models_wait_timeout [Float] bounded seconds GET /api/models
+      #   waits for the hosts' lists
+      def initialize(manager: nil, session_class: nil, state_dir: nil, public_dir: nil,
+                     bridge_wait_timeout: BRIDGE_WAIT_TIMEOUT, markdown: false, turn_view: true, hub: nil,
+                     events_heartbeat: EVENTS_HEARTBEAT, events_queue: EVENTS_QUEUE,
+                     registry: nil, models_wait_timeout: MODELS_WAIT_TIMEOUT)
+        @manager = manager || SessionManager
+        @registry = registry
+        @models_wait_timeout = models_wait_timeout
+        @models_mutex = Mutex.new
+        @models_thread = nil
+        @session_class = session_class || Session
+        @state_dir = state_dir
+        @public_dir = public_dir || File.expand_path("public", __dir__)
+        @bridge_wait_timeout = bridge_wait_timeout
+        @markdown_renderer = MarkdownRenderer.new(enabled: markdown)
+        @turn_view = turn_view
+        @hub = hub
+        @events_heartbeat = events_heartbeat
+        @events_queue = events_queue
+        @server_running = -> { true }
+      end
+
+      def call(env)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = route(env)
+        log_request(env, response, started)
+        response
+      end
+
+      private
+
+      def route(env)
+        req = Rack::Request.new(env)
+        return forbidden unless localhost?(req)
+
+        case [req.request_method, req.path_info]
+        when ["GET", "/"], ["GET", "/index.html"]
+          serve_index(req)
+        when ["GET", "/api/sessions"]
+          handle_list(req)
+        when ["POST", "/api/sessions"]
+          handle_create(req)
+        when ["GET", "/api/info"]
+          handle_info
+        when ["GET", "/api/models"]
+          handle_models
+        when ["GET", "/api/events"]
+          handle_events(req)
+        else
+          # Dynamic routes
+          if (m = %r{\A/api/sessions/([^/]+)/stream\z}.match(req.path_info)) && req.get?
+            return handle_stream(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)/output\z}.match(req.path_info)) && req.get?
+            return handle_output(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)/cancel\z}.match(req.path_info)) && req.post?
+            return handle_cancel(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)/stop\z}.match(req.path_info)) && req.post?
+            return handle_stop(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)/turn\z}.match(req.path_info)) && req.post?
+            return handle_turn(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)/answer\z}.match(req.path_info)) && req.post?
+            return handle_question_answer(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)/question/dismiss\z}.match(req.path_info)) && req.post?
+            return handle_question_dismiss(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)/command\z}.match(req.path_info)) && req.post?
+            return handle_command(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)/images\z}.match(req.path_info)) && req.post?
+            return handle_image_upload(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)/images/([^/]+)\z}.match(req.path_info)) && req.get?
+            return handle_image(req, m[1], m[2])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)\z}.match(req.path_info)) && req.get?
+            return handle_show(req, m[1])
+          end
+          if (m = %r{\A/api/sessions/([^/]+)\z}.match(req.path_info)) && req.delete?
+            return handle_delete(req, m[1])
+          end
+          if req.path_info.start_with?("/assets/") || req.path_info.start_with?("/public/")
+            return serve_static(req)
+          end
+          # Fallback static file serve from public_dir (e.g. /style.css)
+          maybe_static = serve_static(req)
+          return maybe_static if maybe_static[0] != 404
+
+          not_found(path: req.path_info)
+        end
+      rescue StandardError => e
+        Log.exception(:web, "request_failed", e, method: env["REQUEST_METHOD"], path: env["PATH_INFO"])
+        error_response(500, "internal_error", e.message)
+      end
+
+      # API requests at debug level (not the page and its assets): method,
+      # path, status, time. Never a body or the query; only a tail=1 read
+      # (the page's end-of-turn re-read) is marked, to tell it from a full one.
+      def log_request(env, response, started)
+        path = env["PATH_INFO"].to_s
+        return unless path.start_with?("/api/") && Log.level?(:debug)
+
+        tail = env["QUERY_STRING"].to_s.split("&").include?("tail=1") ? { tail: true } : {}
+        Log.debug(:web, "request", sid: path[%r{\A/api/sessions/([^/]+)}, 1], method: env["REQUEST_METHOD"], path: path,
+                                   status: response[0], **tail,
+                                   ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round)
+      end
+
+      def localhost?(req)
+        # Only 127.0.0.1 / ::1 / localhost are allowed. The socket is bound to
+        # 127.0.0.1, but an explicit Host check prevents DNS-rebind tricks.
+        host = req.host.to_s.downcase.split(":").first
+        %w[127.0.0.1 ::1 localhost].include?(host)
+      end
+
+      def forbidden
+        error_response(403, "forbidden", "only 127.0.0.1 is allowed")
+      end
+
+      # The page's scope: ?dir=<folder> lists that folder's project (every
+      # session when the folder is in no repo). A dir that isn't an existing
+      # absolute folder answers 400 before anything else runs.
+      def handle_list(req)
+        dir, error = scope_dir(req.params["dir"])
+        return error if error
+
+        scope = {}
+        root = dir && ProjectScope.root_for(dir)
+        scope[:project_root] = root if root
+        # Lazy retention sweep (once per 24h)
+        if @manager.respond_to?(:retention_sweep_if_due)
+          begin
+            @manager.retention_sweep_if_due(state_dir: @state_dir)
+          rescue StandardError
+            nil
+          end
+        end
+        sort = sanitize_sort(req.params["sort"])
+        order = sanitize_order(req.params["order"])
+        limit = sanitize_limit(req.params["limit"])
+        offset = sanitize_offset(req.params["offset"])
+        return list_from_hub(root, sort: sort, order: order, limit: limit, offset: offset) if @hub
+
+        sessions = if @state_dir
+                     @manager.list_sessions(state_dir: @state_dir, sort: sort, order: order, limit: limit, offset: offset,
+                                            **scope)
+                   else
+                     @manager.list_sessions(sort: sort, order: order, limit: limit, offset: offset, **scope)
+                   end
+        roots = {}
+        payload = sessions.map do |s|
+          owner = session_owner(s.id)
+          session_to_json(s, status: displayed_status(s, owner: owner), owner: owner, root_cache: roots)
+        end
+        # Expose total via header for pagination (total unordered count)
+        headers = { "Content-Type" => "application/json; charset=utf-8", "Cache-Control" => "no-store", "Access-Control-Allow-Origin" => "*" }
+        # Compute total without limit/offset for header
+        if limit || offset.positive?
+          total = if @state_dir
+                    @manager.list_sessions(state_dir: @state_dir, sort: sort, order: order, **scope).size
+                  else
+                    @manager.list_sessions(sort: sort, order: order, **scope).size
+                  end
+          headers["X-Total-Count"] = total.to_s
+        end
+        body = JSON.generate(payload)
+        headers["Content-Length"] = body.bytesize.to_s
+        [200, headers, [body]]
+      end
+
+      # The list from the hub's projection (the page's fallback and the
+      # first paint): the same sort, paging and total as from the files.
+      def list_from_hub(root, sort:, order:, limit:, offset:)
+        all = @hub.snapshot(project_root: root, sort: sort, order: order)
+        page = all.drop(offset)
+        page = page.first(limit) if limit
+        headers = { "Content-Type" => "application/json; charset=utf-8", "Cache-Control" => "no-store", "Access-Control-Allow-Origin" => "*" }
+        headers["X-Total-Count"] = all.size.to_s if limit || offset.positive?
+        body = JSON.generate(page)
+        headers["Content-Length"] = body.bytesize.to_s
+        [200, headers, [body]]
+      end
+
+      # A scope folder from the page: [dir, nil] (dir nil when none was
+      # given), or [nil, a 400 response] when it isn't an existing absolute
+      # folder (a bookmarked worktree deleted since, a typo).
+      def scope_dir(value)
+        return [nil, nil] if value.nil? || value.to_s.strip.empty?
+
+        dir = value.to_s
+        unless dir.start_with?("/") && File.directory?(dir)
+          return [nil, error_response(400, "invalid_dir", "not a folder: #{dir}")]
+        end
+
+        [File.expand_path(dir), nil]
+      end
+
+      # What a second `chi web` probes before starting its own server: this
+      # is chi web, and it knows ?dir (features).
+      def handle_info
+        json_response(200, { app: "chi-web", version: Samagotchi::VERSION, pid: Process.pid, cwd: Dir.pwd,
+                             features: ["dir"] })
+      end
+
+      # The models a new session can start on, spelled as chi spells them
+      # elsewhere: bare for the default host (what default.model holds), and
+      # host:model for another host. The default is the configured model, or
+      # what spawn_session gives a session today. The hosts' lists come from
+      # the registry's cache (60 s; 10 min for a remote host); the route waits
+      # a bounded time for a fresh listing and answers with what it has, a
+      # host that failed or the wait running out noted in +warning+, never a
+      # failure: the default alone is enough for the page.
+      def handle_models
+        default = begin
+          ModelProfile.required_model_name
+        rescue StandardError
+          nil
+        end
+        models = []
+        warnings = []
+        begin
+          registry = host_registry
+          results = await_model_lists(registry)
+          if results.nil?
+            warnings << "the hosts are still listing their models"
+          else
+            default_host = registry.default_entry&.name
+            ordered = results.keys.sort_by { |name| [name == default_host ? 0 : 1, name] }
+            ordered.each do |host|
+              data = results[host]
+              if data[:error]
+                warnings << "#{host}: #{data[:error]}"
+                next
+              end
+              Array(data[:models]).each do |info|
+                id = info.id.to_s
+                next if id.strip.empty? || id.end_with?(":batch")
+
+                models << { name: host == default_host ? id : "#{host}:#{id}", host: host, id: id }
+              end
+            end
+          end
+        rescue StandardError => e
+          warnings << e.message
+        end
+        if default && models.none? { |m| m[:name].casecmp?(default) }
+          models.unshift({ name: default, host: nil, id: default })
+        end
+        payload = { default: default, models: models }
+        payload[:warning] = warnings.join("; ") unless warnings.empty?
+        json_response(200, payload)
+      end
+
+      def host_registry
+        @models_mutex.synchronize { @registry ||= HostRegistry.new }
+      end
+
+      # The hosts' model lists (cached ones as they are), or the last complete
+      # listing (nil when there is none) when this one is not done within the
+      # wait. One listing runs at a time; a request that finds one running
+      # waits on it. A listing that raised raises here.
+      def await_model_lists(registry)
+        thread = @models_mutex.synchronize do
+          unless @models_thread&.alive?
+            @models_thread = Thread.new { registry.list_all_models(force: false) }
+            @models_thread.report_on_exception = false
+          end
+          @models_thread
+        end
+        thread.join(@models_wait_timeout) ? thread.value : registry.cached_results
+      end
+
+      def sanitize_sort(val)
+        %w[created_at updated_at].include?(val.to_s) ? val.to_s : "updated_at"
+      end
+
+      def sanitize_order(val)
+        %w[asc desc].include?(val.to_s) ? val.to_s : "desc"
+      end
+
+      def sanitize_limit(val)
+        return nil if val.nil? || val.to_s.strip.empty?
+        n = val.to_i
+        return nil if n <= 0
+        [n, 1000].min
+      end
+
+      def sanitize_offset(val)
+        return 0 if val.nil? || val.to_s.strip.empty?
+        n = val.to_i
+        n.positive? ? n : 0
+      end
+
+      def handle_create(req)
+        body = parse_json(request_body(req))
+        unless body.is_a?(Hash)
+          return error_response(400, "invalid_json", "invalid JSON body")
+        end
+        prompt = body["prompt"] || body[:prompt]
+        # idle: a session with no first turn, for a first message with
+        # images (the page uploads them into it, then sends the turn).
+        idle = body["idle"] == true
+        if prompt.to_s.strip.empty? && !idle
+          return error_response(400, "missing_fields", "prompt is required")
+        end
+        # dir: the folder the chat starts in (the page's scope); without it,
+        # the server's own cwd.
+        dir, error = scope_dir(body["dir"])
+        return error if error
+
+        folder = dir ? { working_directory: dir } : {}
+        # model: the model the session starts on (the start page's picker,
+        # spelled as GET /api/models lists it); blank means the default.
+        model = (body["model"] || body["model_name"]).to_s.strip
+        folder[:model_name] = model unless model.empty?
+        begin
+          session = @manager.spawn_session(prompt: idle ? nil : prompt.to_s, state_dir: @state_dir, **folder)
+        rescue ArgumentError => e
+          return error_response(400, "invalid_model", e.message) if e.message.match?(/SAMAGOTCHI_DEFAULT_MODEL/)
+          raise
+        end
+        # The worker's Bridge is the single live transport: wait (bounded) for
+        # it so the client can attach without client-side polling.
+        port = await_bridge_port(session.id)
+        # The projection holds it before the page hears back (no tick wait).
+        @hub&.touch(session.id)
+        json_response(201, session_to_json(session).merge(bridge_port: port))
+      end
+
+      def handle_show(req, id)
+        session = @session_class.load(id, state_dir: default_state_dir)
+        # Read-only preview: selecting a session never spawns a worker.
+        # The worker is woken only on POST /turn (handle_turn) via
+        # SessionManager.resume_session + write_turn_input. This avoids
+        # replaying last_prompt and spamming workers on preview scrub.
+        # last_event_seq is nil when no live bridge, so the frontend stays
+        # silent until the first Send.
+        #
+        # A live worker's snapshot is the truth (the session file lags its
+        # Engine): the messages, the turn in progress and the prompts queued
+        # behind it, all at one event_seq the client streams on from.
+        live = bridge_get_json(id, "snapshot")
+        turn_snapshot = live && live["snapshot"]
+        # ?cards=1: the page's re-read when a card arrives, for its rendered
+        # body (the stream carries the card's plain text only).
+        if req.params["cards"] == "1"
+          return json_response(200, { cards: cards_for_display(turn_snapshot) })
+        end
+        snapshot = live && live["session_state_snapshot"]
+        last_event_seq = snapshot ? snapshot["event_seq"] : bridge_event_seq(id)
+        current_turn = turn_snapshot && turn_snapshot["current_turn"]
+        pending = if turn_snapshot
+                    current_turn && current_turn["pending_question"]
+                  elsif session.respond_to?(:pending_question)
+                    session.pending_question
+                  end
+        owner = session_owner(id)
+        # A /model in the worker changes it before the file catches up.
+        session.model_name = snapshot["model_name"] if snapshot && !snapshot["model_name"].to_s.empty?
+        session_json = session_to_json(session, status: displayed_status(session, snapshot, owner: owner), owner: owner)
+        # What the worker's server said it served for that model (after a turn).
+        if snapshot
+          session_json = session_json.merge(served_model: snapshot["served_model"], served_model_for: snapshot["served_model_for"])
+        end
+        raw_messages = turn_snapshot ? turn_snapshot["messages"] : session.messages
+        timing = timing_payload(id, live_metrics: snapshot && snapshot["metrics"])
+        # ?tail=1: the page's re-read at the end of a turn wants the final
+        # answer's rendered markdown, the status and the timing, not the
+        # whole history again (nor a render of every earlier answer).
+        if req.params["tail"] == "1"
+          return json_response(200, {
+            tail: true,
+            session: session_json,
+            messages: last_assistant_for_display(raw_messages),
+            markdown_warning: @markdown_renderer.warning,
+            timing: timing
+          })
+        end
+
+        json_response(200, {
+          session: session_json,
+          history: read_history(id),
+          messages: messages_for_display(raw_messages, parts: req.params["parts"] == "1"),
+          current_turn: current_turn,
+          queued: turn_snapshot ? Array(turn_snapshot["queued"]) : [],
+          recap: turn_snapshot && turn_snapshot["recap"],
+          saved_recap: saved_recap_for(id, session, turn_snapshot),
+          continue_offer: turn_snapshot && turn_snapshot["continue_offer"],
+          guardrail_warning: turn_snapshot && turn_snapshot["guardrail_warning"],
+          plugin_warning: turn_snapshot && turn_snapshot["plugin_warning"],
+          # Plugins' slow setup still running (chi.init): the page's init row.
+          init_tasks: turn_snapshot ? Array(turn_snapshot["init_tasks"]) : [],
+          cards: cards_for_display(turn_snapshot),
+          # The composer's / autocomplete; the built-ins until a worker
+          # names its plugins' too.
+          commands: turn_snapshot&.fetch("commands", nil) || SessionCommands.builtin_registry.listing,
+          markdown_warning: @markdown_renderer.warning,
+          pending_question: pending,
+          last_event_seq: last_event_seq,
+          # The stream cursor `<seq>-<epoch>`: a later worker resets it
+          # instead of taking the seq as its own. Only the snapshot has it.
+          last_event_id: turn_snapshot && turn_snapshot["event_id"],
+          timing: timing
+        })
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      # The worker's last cards and between-turns notices (Bridge
+      # snapshot[:cards]), a card's body as body_html: rendered markdown
+      # when the renderer is on, else the escaped text in a <pre>.
+      # @return [Array<Hash>] [] without a live worker
+      def cards_for_display(turn_snapshot)
+        Array(turn_snapshot && turn_snapshot["cards"]).filter_map do |card|
+          next unless card.is_a?(Hash)
+          next card unless card["type"].to_s == "card"
+
+          card.merge("body_html" => card_body_html(card["body"].to_s))
+        end
+      end
+
+      def card_body_html(body)
+        return "" if body.strip.empty?
+
+        html = @markdown_renderer.render(body) if @markdown_renderer.available?
+        html || "<pre>#{CGI.escapeHTML(body)}</pre>"
+      end
+
+      def handle_question_answer(req, id)
+        session = @session_class.load(id, state_dir: default_state_dir) rescue nil
+        return error_response(404, "not_found", "Session not found: #{id}") unless session
+
+        body = parse_json(request_body(req))
+        unless body.is_a?(Hash)
+          return error_response(400, "invalid_json", "invalid JSON body")
+        end
+        qid = body["id"] || body[:id] || body["question_id"] || body[:question_id]
+        selected = body["selected"] || body[:selected] || body["selection"] || body[:selection]
+        freeform = body["freeform"] || body[:freeform] || body["other"] || body[:other]
+        # Allow payload nested under answer
+        if body["answer"].is_a?(Hash)
+          ans = body["answer"]
+          qid ||= ans["id"] || ans[:id]
+          selected ||= ans["selected"] || ans[:selected]
+          freeform ||= ans["freeform"] || ans[:freeform]
+        end
+        if qid.to_s.strip.empty?
+          return error_response(400, "missing_fields", "id is required")
+        end
+        # Try live Engine via Bridge first (in-process answer without file IPC)
+        client = bridge_client(id)
+        if client
+          begin
+            reply = client.answer(id: qid, selected: selected, freeform: freeform)
+            return json_response(200, { status: "answered", session_id: id, id: qid }) if reply.ok?
+            # Read after its deadline and dropped (see #worker_timeout).
+            return worker_timeout("the answer was not sent") if reply.status == 408
+
+            # Pass the bridge's verdict through: 409 = another client answered
+            # first (or the question was cancelled), 400 = invalid selection.
+            if [400, 409].include?(reply.status)
+              detail = reply.json&.dig("detail") || "answer rejected"
+              return error_response(reply.status, reply.status == 409 ? "question_not_pending" : "invalid_answer", detail)
+            end
+          rescue Errno::ETIMEDOUT
+            return worker_timeout("the answer was not sent")
+          rescue StandardError
+            nil
+          end
+        end
+        error_response(503, "not_live", "no live bridge for session #{id}")
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      # Leave the pending question unanswered (the card's Dismiss). A question
+      # only exists while its worker waits on it, so this needs a live bridge.
+      def handle_question_dismiss(req, id)
+        body = parse_json(request_body(req))
+        return error_response(400, "invalid_json", "invalid JSON body") unless body.is_a?(Hash)
+
+        qid = body["id"].to_s
+        return error_response(400, "missing_fields", "id is required") if qid.strip.empty?
+
+        client = bridge_client(id)
+        return error_response(503, "not_live", "no live bridge for session #{id}") unless client
+
+        reply = client.dismiss_question(id: qid)
+        case reply.status
+        when 200 then json_response(200, { status: "dismissed", session_id: id, id: qid })
+        when 409 then error_response(409, "question_not_pending", reply.json&.dig("detail") || "question not pending")
+        when 408 then worker_timeout("the question was not dismissed")
+        when 404
+          error_response(501, "not_supported", BridgeClient.stale_worker_message(id, cant: "dismiss questions"))
+        else error_response(503, "not_live", "no live bridge for session #{id}")
+        end
+      rescue Errno::ETIMEDOUT
+        worker_timeout("the question was not dismissed")
+      rescue StandardError
+        error_response(503, "not_live", "no live bridge for session #{id}")
+      end
+
+      # A session command typed in the composer (/model, /models, !rollback,
+      # !cmd, /continue): the worker runs it (woken as for a turn) and every
+      # UI gets its :command_ran. Needs the worker's Bridge.
+      def handle_command(req, id)
+        body = parse_json(request_body(req))
+        return error_response(400, "invalid_json", "invalid JSON body") unless body.is_a?(Hash)
+
+        line = body["line"].to_s.strip
+        return error_response(400, "missing_fields", "line is required") if line.empty?
+
+        @manager.resume_session(id, state_dir: @state_dir) if @manager.respond_to?(:resume_session)
+        client = live_bridge_client(id)
+        return error_response(503, "not_live", "no live bridge for session #{id}") unless client
+
+        reply = client.post_command(line: line, client_id: body["client_id"])
+        case reply.status
+        when 202 then json_response(202, reply.json || { status: "accepted" })
+        when 400 then error_response(400, reply.json&.dig("error") || "unknown_command", reply.json&.dig("detail") || "not a session command")
+        when 408 then worker_timeout("the command was not run")
+        when 404
+          error_response(501, "not_supported", BridgeClient.stale_worker_message(id, cant: "run commands"))
+        else error_response(503, "not_live", "no live bridge for session #{id}")
+        end
+      rescue SessionManager::OwnedByTUI => e
+        error_response(409, "owned_by_tui", e.message)
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      rescue Errno::ETIMEDOUT
+        worker_timeout("the command was not run")
+      rescue SystemCallError, IOError
+        error_response(503, "not_live", "no live bridge for session #{id}")
+      end
+
+      # The worker didn't take a request in time: its read timed out, or the
+      # Bridge read it after its deadline (408 deadline_passed) and dropped
+      # it. Either way +what+ didn't happen, and a frozen worker that wakes
+      # won't do it (BridgeClient::DEADLINE_SHARE).
+      def worker_timeout(what)
+        error_response(504, "worker_timeout", "the session's worker did not answer, so #{what}")
+      end
+
+      def handle_output(req, id)
+        # Query ?since= may be an ISO8601 time or numeric mtime; we treat it as Time parse.
+        since_param = req.params["since"]
+        since_time = parse_since(since_param)
+        session = @session_class.load(id, state_dir: default_state_dir)
+        raw = @manager.read_responses(id, since_time: since_time, state_dir: @state_dir)
+        # Strip wire tokens server-side so the client never sees <|tool_call> etc.
+        rendered = raw.map { |chunk| OutputFormatter.strip(chunk) }.reject(&:empty?)
+        json_response(200, { session_id: session.id, output: rendered })
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      def handle_turn(req, id)
+        body = parse_json(request_body(req))
+        unless body.is_a?(Hash)
+          return error_response(400, "invalid_json", "invalid JSON body")
+        end
+        prompt = body["prompt"] || body[:prompt]
+        client_id = body["client_id"] || body[:client_id]
+        if prompt.to_s.strip.empty?
+          return error_response(400, "missing_fields", "prompt is required")
+        end
+        images = turn_images(id, body["images"])
+        return error_response(400, "bad_images", images) if images.is_a?(String)
+
+        result = SessionManager.deliver_turn(id, prompt: prompt.to_s, client_id: client_id, images: images, state_dir: @state_dir,
+                                             manager: @manager, bridge: -> { live_bridge_client(id) })
+        case result[:status]
+        when :accepted then json_response(202, result[:ack])
+        when :refused then json_response(result[:code], result[:ack])
+        when :timeout then error_response(504, "worker_timeout", result[:ack]["detail"])
+        else error_response(500, "enqueue_failed", "could not write turn input")
+        end
+      rescue SessionManager::OwnedByTUI => e
+        error_response(409, "owned_by_tui", e.message)
+      rescue SessionManager::ImagesUnsupported => e
+        error_response(409, "images_unsupported", e.message)
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      # A turn's images as [{file:, name:}] (refs to uploads already in the
+      # session's images/), or a String saying what's wrong. Never a path.
+      def turn_images(id, raw)
+        return [] if raw.nil?
+        return "images must be a list" unless raw.is_a?(Array)
+
+        session_dir = image_session_dir(id)
+        return "unknown session" unless session_dir
+
+        raw.map do |image|
+          return "each image must be {file:, name:}" unless image.is_a?(Hash)
+          return "images are refs to uploaded files, not paths" if image.key?("path") || image.key?(:path)
+          return "unknown image" unless ImageStore.valid_ref?(session_dir, image)
+
+          { file: (image["file"] || image[:file]).to_s, name: File.basename((image["name"] || image[:name]).to_s)[0, 120] }
+        end
+      end
+
+      # The session's folder, or nil for an id that isn't one.
+      def image_session_dir(id)
+        return nil unless SESSION_ID_RE.match?(id.to_s)
+
+        @session_class.load(id, state_dir: default_state_dir)
+        Session.session_dir(id, state_dir: default_state_dir)
+      rescue ArgumentError
+        nil
+      end
+
+      # POST /api/sessions/:id/images: the raw image as the body (a paste or
+      # a drop), ?name= for its file name. Stored like any other image
+      # (converted, downscaled); answers the ref the turn then names.
+      def handle_image_upload(req, id)
+        session_dir = image_session_dir(id)
+        return error_response(404, "not_found", "unknown session") unless session_dir
+
+        length = req.content_length.to_i
+        if length > MAX_IMAGE_UPLOAD_BYTES
+          return error_response(413, "too_large", "an image may be up to #{MAX_IMAGE_UPLOAD_BYTES / 1024 / 1024} MB")
+        end
+
+        bytes = request_body(req, MAX_IMAGE_UPLOAD_BYTES + 1).to_s.b
+        if bytes.bytesize > MAX_IMAGE_UPLOAD_BYTES
+          return error_response(413, "too_large", "an image may be up to #{MAX_IMAGE_UPLOAD_BYTES / 1024 / 1024} MB")
+        end
+
+        name = File.basename(req.params["name"].to_s)[0, 120]
+        ref = ImageStore.ingest(session_dir, bytes: bytes, name: name.empty? ? "image" : name, source: "user")
+        json_response(201, ref)
+      rescue ImageStore::Error => e
+        error_response(422, "bad_image", e.message)
+      end
+
+      # GET /api/sessions/:id/images/<hash>.<ext>: a stored image (only
+      # raster types; never svg), for the page's thumbnails.
+      def handle_image(_req, id, name)
+        session_dir = image_session_dir(id)
+        return not_found(path: "images/#{name}") unless session_dir && IMAGE_NAME_RE.match?(name.to_s)
+
+        path = File.join(session_dir, ImageStore::DIR, name)
+        return not_found(path: "images/#{name}") unless File.file?(path) && !File.symlink?(path)
+
+        body = File.binread(path)
+        [200, { "Content-Type" => IMAGE_TYPES.fetch(File.extname(name).delete(".")), "Content-Length" => body.bytesize.to_s,
+                "X-Content-Type-Options" => "nosniff", "Cache-Control" => "private, max-age=86400" }, [body]]
+      end
+
+      # The session's Bridge, waiting briefly for one a resume just spawned.
+      # @return [BridgeClient, nil]
+      def live_bridge_client(id)
+        port = bridge_sidecar_port(id) || await_bridge_port(id, timeout: [@bridge_wait_timeout.to_f, 5.0].min)
+        port && BridgeClient.new(session_id: id, port: port, host: DEFAULT_HOST)
+      end
+
+      # The process holding the session: {"pid", "kind" => "worker"|"tui"}, or
+      # nil. A worker always runs a Bridge; a TUI (plain `chi`) doesn't share.
+      def session_owner(id)
+        return nil unless @manager.respond_to?(:session_owner)
+
+        @manager.session_owner(id, state_dir: @state_dir)
+      rescue StandardError
+        nil
+      end
+
+      def handle_cancel(req, id)
+        # Validate session exists
+        begin
+          @session_class.load(id, state_dir: default_state_dir)
+        rescue ArgumentError => e
+          return error_response(404, "not_found", e.message)
+        end
+
+        body = request_body(req)
+        reason = "user"
+        unless body.nil? || body.strip.empty?
+          parsed = parse_json(body)
+          if parsed.is_a?(Hash)
+            r = parsed["reason"] || parsed[:reason] || parsed["cancellation_reason"]
+            r = r.to_s.strip
+            reason = if r.empty? then "user"
+                     elsif CANCEL_REASONS.include?(r) then r
+                     else "manual"
+                     end
+          end
+        end
+
+        # Try direct bridge cancel first (in-process, low latency)
+        client = bridge_client(id)
+        if client
+          begin
+            reply = client.cancel(reason: reason)
+            if reply.status == 202
+              return json_response(202, { status: "cancel_requested", session_id: id, reason: reason, via: "bridge" })
+            end
+            # The bridge answers 409 when there is no active turn to cancel.
+            if reply.status == 409
+              return json_response(409, { error: "not_running", detail: "no active turn to cancel", session_id: id })
+            end
+          rescue StandardError
+            nil
+          end
+        end
+
+        error_response(503, "not_live", "no live bridge for session #{id}")
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      def handle_stop(_req, id)
+        # Bounded, so a Rack thread isn't held long; a worker still exiting
+        # after it just means an immediate resume finds it (rare).
+        @manager.stop_session(id, state_dir: @state_dir, wait: STOP_WAIT_SECONDS)
+        @hub&.touch(id)
+        json_response(200, { status: "stopped", session_id: id })
+      rescue SessionManager::OwnedByTUI => e
+        error_response(409, "owned_by_tui", e.message)
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      # DELETE /api/sessions/:id: the session for good. A live worker is
+      # stopped first (the page's confirm says so); a chi REPL's session is
+      # refused.
+      def handle_delete(_req, id)
+        result = @manager.delete_session(id, state_dir: @state_dir, stop: true, wait: STOP_WAIT_SECONDS)
+        @hub&.touch(result[:id])
+        json_response(200, { status: "deleted", session_id: result[:id], stopped: result[:stopped] })
+      rescue SessionManager::OwnedByTUI
+        error_response(409, "owned_by_tui", "session #{id} is open in a chi REPL; close it there first")
+      rescue SessionManager::DeleteRefused => e
+        error_response(409, e.reason.to_s, "#{e.message}; try again in a moment")
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
+      def handle_stream(req, id)
+        # Validate session exists
+        begin
+          @session_class.load(id, state_dir: default_state_dir)
+        rescue ArgumentError
+          return error_response(404, "not_found", "Session not found: #{id}")
+        end
+
+        # Single live transport: proxy to the session's Bridge. When no live
+        # worker exists there is nothing to stream — history is available via
+        # GET /api/sessions/:id/output.
+        bridge_port = bridge_sidecar_port(id)
+        # A resume just spawned the worker: its bridge may still be binding.
+        # Wait briefly for it so the first SSE connect lands on a live bridge
+        # instead of an instantly-closed empty 200 / 503 during startup.
+        if bridge_port.nil? && @bridge_wait_timeout.to_i.positive?
+          bridge_port = await_bridge_port(id, timeout: [@bridge_wait_timeout.to_f, 2.0].min)
+        end
+        return error_response(503, "not_live", "no live bridge for session #{id}") unless bridge_port
+
+        headers = {
+          "Content-Type" => "text/event-stream",
+          "Cache-Control" => "no-cache",
+          "Connection" => "keep-alive",
+          "X-Accel-Buffering" => "no",
+          "Access-Control-Allow-Origin" => "*"
+        }
+
+        # Handlers that buffer enumerable bodies before responding (rackup's
+        # WEBrick does `body.each` to completion) hang forever on an unbounded
+        # SSE body — the browser never even receives the status line. When the
+        # handler supports hijacking, stream frames straight to the socket
+        # instead of returning an enumerable.
+        if req.env["rack.hijack?"]
+          hijack = sse_hijack(id, req, bridge_port)
+          return [200, headers.merge("rack.hijack" => hijack), []]
+        end
+
+        query = req.query_string.to_s.empty? ? "" : "?#{req.query_string}"
+        [200, headers, ProxyStreamBody.new(host: DEFAULT_HOST, port: bridge_port, session_id: id, query: query, headers: req.env,
+                                           server_running: @server_running)]
+      end
+
+      # GET /api/events: the session list as one SSE stream per tab. The
+      # first frame is the hub's snapshot (scoped by ?dir= as the list is),
+      # then `session` for an upsert and `session_gone` for a removal, with
+      # a `: ping` while idle. Frame ids are the hub's seq, for the log's
+      # sake: there is no replay, a reconnect starts with a fresh snapshot.
+      def handle_events(req)
+        return error_response(503, "no_hub", "this chi web has no session hub") unless @hub
+
+        dir, error = scope_dir(req.params["dir"])
+        return error if error
+
+        root = dir && ProjectScope.root_for(dir)
+        headers = {
+          "Content-Type" => "text/event-stream",
+          "Cache-Control" => "no-cache",
+          "Connection" => "keep-alive",
+          "X-Accel-Buffering" => "no",
+          "Access-Control-Allow-Origin" => "*"
+        }
+        body = EventsBody.new(hub: @hub, project_root: root, heartbeat: @events_heartbeat, capacity: @events_queue,
+                              server_running: @server_running)
+        # As handle_stream: hijack when the handler offers it (rackup's
+        # WEBrick buffers enumerable bodies), else an enumerable body.
+        if req.env["rack.hijack?"]
+          hijack = lambda do |io|
+            body.each do |chunk|
+              io.write(chunk)
+              io.flush
+            end
+          rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+            nil # the tab went away
+          end
+          return [200, headers.merge("rack.hijack" => hijack), []]
+        end
+
+        [200, headers, body]
+      end
+
+      # Rack hijack lambda (env["rack.hijack?"] truthy): pipes the bridge's SSE
+      # frames directly to the client socket until it disconnects. The handler
+      # (WEBrick via rackup) has already sent the status line + headers, so
+      # only body bytes go to the socket here.
+      def sse_hijack(id, req, port)
+        lambda do |io|
+          query = req.query_string.to_s.empty? ? "" : "?#{req.query_string}"
+          body = ProxyStreamBody.new(host: DEFAULT_HOST, port: port, session_id: id, query: query, headers: req.env,
+                                    server_running: @server_running)
+          body.each { |chunk| io.write(chunk) }
+        rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+          nil # client went away — end the stream quietly
+        rescue StandardError => e
+          Log.warn(:web, "proxy_failed", sid: id, port: port, error: e.class.name, msg: e.message)
+          nil
+        end
+      end
+
+      # Bounded wait for a freshly-spawned worker's bridge sidecar so the
+      # response hands the client a live transport without client-side polling.
+      # Returns the bridge port, or nil when it is not up by the deadline (the
+      # session still exists; EventSource auto-reconnect covers late binders).
+      def await_bridge_port(session_id, timeout: @bridge_wait_timeout)
+        return nil if timeout.nil? || timeout <= 0
+
+        BridgeClient.poll(timeout, interval: BridgeClient::SPAWN_POLL_INTERVAL) { bridge_sidecar_port(session_id) }
+      rescue StandardError
+        nil
+      end
+
+      # Port of the session's live Bridge (stale sidecars are removed), or nil.
+      def bridge_sidecar_port(session_id)
+        dir = @session_class.session_dir(session_id, state_dir: default_state_dir)
+        BridgeClient.sidecar_port(dir, host: DEFAULT_HOST)
+      rescue StandardError
+        nil
+      end
+
+      # @return [BridgeClient, nil] a client for the session's live Bridge
+      def bridge_client(session_id)
+        port = bridge_sidecar_port(session_id)
+        port && BridgeClient.new(session_id: session_id, port: port, host: DEFAULT_HOST)
+      end
+
+      # Read the live Engine state over the bridge (raw GET /session/:id/state).
+      # @return [Hash, nil] parsed JSON body, or nil when no live bridge / timeout.
+      def bridge_get_json(session_id, path)
+        bridge_client(session_id)&.get_json(path)
+      end
+
+      # Monotonic SSE cursor for a live bridge session, else nil.
+      def bridge_event_seq(session_id)
+        bridge_client(session_id)&.event_seq
+      end
+
+      def serve_index(req)
+        path = File.join(@public_dir, "index.html")
+        if File.file?(path)
+          body = File.read(path).sub("<body>", "<body #{index_data_attributes(req)}>")
+          [200, {
+            "Content-Type" => "text/html; charset=utf-8",
+            "Content-Length" => body.bytesize.to_s,
+            "Cache-Control" => "no-store, no-cache, must-revalidate, max-age=0",
+            "Pragma" => "no-cache",
+            "Expires" => "0"
+          }, [body]]
+        else
+          [200, { "Content-Type" => "text/html" }, ["<h1>Chi Web</h1><p>Public dir missing: #{@public_dir}</p>"]]
+        end
+      end
+
+      def serve_static(req)
+        # Serve files under public_dir for /assets/* and bare paths
+        rel = req.path_info.sub(%r{\A/(assets|public)/}, "")
+        rel = req.path_info.sub(%r{\A/}, "") if rel == req.path_info
+        # Prevent directory traversal
+        rel = rel.split("/").reject { |p| p == ".." || p.empty? }.join("/")
+        full = File.join(@public_dir, rel)
+        if File.file?(full) && full.start_with?(@public_dir)
+          body = File.binread(full)
+          ctype = mime_type(full)
+          [200, { "Content-Type" => ctype, "Content-Length" => body.bytesize.to_s, "Cache-Control" => "public, max-age=3600" }, [body]]
+        else
+          not_found(path: req.path_info)
+        end
+      end
+
+      def mime_type(path)
+        case File.extname(path).downcase
+        when ".html" then "text/html; charset=utf-8"
+        when ".js" then "application/javascript; charset=utf-8"
+        when ".css" then "text/css; charset=utf-8"
+        when ".json" then "application/json; charset=utf-8"
+        when ".svg" then "image/svg+xml"
+        else "application/octet-stream"
+        end
+      end
+
+      # status is turn state (idle/running): SessionSummary.displayed_status,
+      # unless the manager can't tell who owns a session (then the file's
+      # word stands).
+      def displayed_status(session, snapshot = nil, owner: session_owner(session.id))
+        unless @manager.respond_to?(:session_owner)
+          return snapshot["status"] if snapshot.is_a?(Hash) && snapshot["status"]
+
+          return session.status
+        end
+
+        SessionSummary.displayed_status(session, snapshot, owner: owner)
+      end
+
+      # @param owner [Hash, nil] #session_owner; its kind is shown as `owner`
+      def session_to_json(s, status: s.status, owner: nil, root_cache: nil)
+        SessionSummary.build(s, status: status, owner: owner, root_cache: root_cache,
+                                session_dir: @session_class.session_dir(s.id, state_dir: default_state_dir))
+      end
+
+      def timing_payload(session_id, live_metrics: nil)
+        persisted = read_analytics(session_id)
+        source = if live_metrics.is_a?(Hash)
+                   persisted.merge(live_metrics).merge(
+                     "started_at" => persisted["started_at"] || live_metrics["started_at"],
+                     "turn_records" => merge_timing_records(persisted["turn_records"], live_metrics["turn_records"]),
+                     "tool_records" => merge_timing_records(persisted["tool_records"], live_metrics["tool_records"])
+                   )
+                 else
+                   persisted
+                 end
+        started_at = source["started_at"]
+        last_activity_at = source["last_activity_at"]
+        {
+          started_at: started_at,
+          last_activity_at: last_activity_at,
+          session_duration_ms: session_duration_ms(started_at, last_activity_at, active: live_metrics.is_a?(Hash)),
+          turn_records: Array(source["turn_records"]),
+          tool_records: Array(source["tool_records"]),
+          active_turn: source["active_turn"],
+          active_tools: Array(source["active_tools"])
+        }
+      end
+
+      def read_analytics(session_id)
+        path = File.join(@session_class.session_dir(session_id, state_dir: default_state_dir), "analytics.json")
+        return {} unless File.file?(path)
+
+        data = JSON.parse(File.read(path))
+        data.is_a?(Hash) ? data : {}
+      rescue JSON::ParserError, SystemCallError
+        {}
+      end
+
+      def merge_timing_records(persisted, live)
+        (Array(persisted) + Array(live)).each_with_object({}) do |record, records|
+          next unless record.is_a?(Hash)
+
+          id = record["id"] || record[:id]
+          records[id] = record if id
+        end.values
+      end
+
+      def session_duration_ms(started_at, last_activity_at, active:)
+        started = Time.iso8601(started_at.to_s)
+        finished = active ? Time.now : Time.iso8601(last_activity_at.to_s)
+        [((finished - started) * 1000).round, 0].max
+      rescue ArgumentError
+        nil
+      end
+
+      # The recap saved with the session and how many user turns came since:
+      # a live worker's (it counts against its Engine's messages), else
+      # recap.json against the session file. A stopped session gets its
+      # recap without a worker being woken.
+      # @return [Hash, nil] {text:, turns_since:}
+      def saved_recap_for(id, session, turn_snapshot)
+        if turn_snapshot
+          saved = turn_snapshot["saved_recap"]
+          return saved && { text: saved["text"], turns_since: saved["turns_since"].to_i }
+        end
+
+        saved = RecapStore.read(@session_class.session_dir(id, state_dir: default_state_dir))
+        return nil unless saved
+
+        messages = Array(session.messages)
+        since = messages.drop(saved[:covered].to_i).count { |m| (m[:role] || m["role"]).to_s == "user" }
+        { text: saved[:text], turns_since: since }
+      rescue StandardError
+        nil
+      end
+
+      def read_history(id)
+        raw = @manager.read_responses(id, since_time: nil, state_dir: @state_dir)
+        raw.map { |chunk| OutputFormatter.strip(chunk) }.reject(&:empty?)
+      rescue StandardError
+        []
+      end
+
+      # @param msgs [Array<Hash>] a session's messages; symbol keys from disk,
+      #   string keys from a Bridge snapshot
+      # @param parts [Boolean] the turn view's reload (?parts=1): each
+      #   assistant message also carries what it did (MessageParts: thinking,
+      #   tool calls with params and output), and a message with nothing to
+      #   show but that (a text-less step) is kept with empty content
+      def messages_for_display(msgs, parts: false)
+        filtered = []
+        list = Array(msgs)
+        list.each_with_index do |m, index|
+          role = (m[:role] || m["role"]).to_s
+          content = (m[:content] || m["content"]).to_s
+          if Samagotchi::ContextNote.note?(m)
+            filtered << { role: "note", content: Samagotchi::ContextNote.text_of(m), label: Samagotchi::ContextNote.label_of(m) }
+            next
+          end
+          next if role == "system"
+          next if role == "tool_response"
+
+          stripped = Samagotchi::OutputFormatter.strip_markup(content)
+          did = parts && %w[model assistant].include?(role) ? message_parts(list, index) : nil
+          next if stripped.empty? && did.nil?
+
+          norm_role = role == "model" ? "assistant" : role
+          # normalize assistant vs model, keep user as is
+          norm_role = "assistant" if norm_role == "assistant" || norm_role == "model"
+          norm_role = "user" if norm_role == "user"
+          next unless %w[user assistant].include?(norm_role)
+
+          message = { role: norm_role, content: stripped }
+          images = m[:images] || m["images"]
+          message[:images] = Array(images).map { |ref| ImageStore.symbolize(ref).slice(:file, :name, :width, :height) } if norm_role == "user" && images.is_a?(Array) && !images.empty?
+          message[:html] = @markdown_renderer.render(stripped) if norm_role == "assistant" && !stripped.empty? && @markdown_renderer.available?
+          message[:parts] = did if did
+          filtered << message
+        end
+        filtered
+      rescue StandardError
+        []
+      end
+
+      # The parts of the assistant message at +index+, with the tool_response
+      # messages right after it.
+      def message_parts(list, index)
+        responses = list.drop(index + 1).take_while { |r| (r[:role] || r["role"]).to_s == "tool_response" }
+        MessageParts.for_message(list[index], responses)
+      end
+
+      # The last message messages_for_display shows as an answer, as a list of
+      # at most one: walked backwards so only that one is rendered.
+      def last_assistant_for_display(msgs)
+        Array(msgs).reverse_each do |m|
+          shown = messages_for_display([m]).first
+          return [shown] if shown && shown[:role] == "assistant"
+        end
+        []
+      end
+
+      def parse_json(str)
+        return nil if str.nil? || str.strip.empty?
+
+        JSON.parse(str)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def parse_since(val)
+        return nil if val.nil? || val.to_s.strip.empty?
+
+        # Try ISO8601, then float timestamp
+        Time.iso8601(val.to_s)
+      rescue ArgumentError
+        begin
+          Time.at(Float(val.to_s))
+        rescue StandardError
+          nil
+        end
+      end
+
+      def default_state_dir
+        @state_dir || Session.default_state_dir
+      end
+
+      # The sessions folder as the page shows it: ~ for the home folder.
+      def sessions_dir_label
+        home_label(File.expand_path(default_state_dir))
+      end
+
+      def home_label(dir)
+        home = Dir.home
+        return "~" if dir == home
+
+        dir.start_with?("#{home}/") ? "~#{dir.delete_prefix(home)}" : dir
+      end
+
+      # <body> data for the page: where sessions are stored, where an
+      # all-view new chat starts (the server's cwd), and, when ?dir names a
+      # folder in a repo, that project's name and root. A bad dir adds
+      # nothing here: the list call answers 400 and the page says so.
+      def index_data_attributes(req)
+        attrs = { "sessions-dir" => sessions_dir_label, "server-dir" => home_label(Dir.pwd) }
+        attrs["turn-view"] = "1" if turn_view?(req.params["view"])
+        dir, = scope_dir(req.params["dir"])
+        root = dir && ProjectScope.root_for(dir)
+        if root
+          attrs["project-name"] = File.basename(root)
+          attrs["project-dir"] = home_label(root)
+        elsif dir.nil?
+          # The all view's way back: the project view it came from
+          # (?from=), else the project chi web runs in.
+          back, = scope_dir(req.params["from"])
+          back ||= Dir.pwd
+          if (back_root = ProjectScope.root_for(back))
+            attrs["back-name"] = File.basename(back_root)
+            attrs["back-dir"] = back
+          end
+        end
+        attrs.map { |key, value| %(data-#{key}="#{Rack::Utils.escape_html(value)}") }.join(" ")
+      end
+
+      # The turn view for this page load: ?view=turn or ?view=chat wins,
+      # anything else leaves the config's choice.
+      def turn_view?(param)
+        case param
+        when "turn" then true
+        when "chat" then false
+        else @turn_view
+        end
+      end
+
+      def json_response(status, payload)
+        body = JSON.generate(payload)
+        [status, { "Content-Type" => "application/json; charset=utf-8", "Content-Length" => body.bytesize.to_s, "Cache-Control" => "no-store", "Access-Control-Allow-Origin" => "*" }, [body]]
+      end
+
+      # The request body, "" when there is none: WEBrick (through rackup)
+      # raises LengthRequired on reading a POST that has neither a
+      # Content-Length nor a chunked body (plain `curl -X POST`).
+      def request_body(req, limit = nil)
+        return "" if req.get_header("CONTENT_LENGTH").nil? && req.get_header("HTTP_TRANSFER_ENCODING").nil?
+
+        req.body.read(*limit)
+      end
+
+      def error_response(status, code, detail)
+        json_response(status, { error: code, detail: detail })
+      end
+
+
+      def not_found(path:)
+        error_response(404, "not_found", "not found: #{path}")
+      end
+
+      # One tab's GET /api/events: a bounded queue behind a lambda sink,
+      # subscribed and snapshotted as one step under the hub's lock, then
+      # drained onto the socket. The loop ends when the hub stops or the
+      # server leaves :Running (rackup's WEBrick joins every request thread
+      # before returning, so a loop that waited on the queue alone would
+      # hang Ctrl-C while a tab is open), and when the queue overflowed:
+      # the reconnect's snapshot is the recovery.
+      class EventsBody
+        # Subscribes now: the snapshot is the list as of the request, and
+        # what changes between here and the socket queues up behind it.
+        def initialize(hub:, project_root:, heartbeat:, capacity:, server_running:)
+          @hub = hub
+          @project_root = project_root
+          @heartbeat = heartbeat
+          @server_running = server_running
+          @queue = Bridge::BoundedQueue.new(capacity: capacity)
+          @handle, @snapshot = @hub.subscribe(->(event) { @queue.push(event) }, snapshot: true, project_root: project_root)
+        end
+
+        def each
+          yield frame(nil, "snapshot", sessions: @snapshot)
+          last_write = monotonic
+          loop do
+            event = @queue.pop([@heartbeat, EVENTS_POLL].min)
+            if event
+              break if @queue.overflow_dropped?
+
+              next unless in_scope?(event)
+
+              yield frame(event.seq, event.type, event.data)
+              last_write = monotonic
+            else
+              # What was queued before the stop still goes out.
+              break if @hub.stopped? || !@server_running.call
+
+              if monotonic - last_write >= @heartbeat
+                yield ": ping\r\n\r\n"
+                last_write = monotonic
+              end
+            end
+          end
+        ensure
+          close
+        end
+
+        # Rack calls it when the body is done with, served or not.
+        def close
+          @handle.unsubscribe
+        end
+
+        private
+
+        # A session outside ?dir's project is not this tab's (its removal
+        # still goes out: harmless).
+        def in_scope?(event)
+          return true if @project_root.nil? || event.type != "session"
+
+          event.data[:session][:project_root] == @project_root
+        end
+
+        def frame(id, type, data)
+          lines = []
+          lines << "id: #{id}" if id
+          lines << "event: #{type}"
+          JSON.generate(data).each_line { |line| lines << "data: #{line.chomp}" }
+          lines.join("\r\n") + "\r\n\r\n"
+        end
+
+        def monotonic
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+
+      # Proxy body that streams from the per-session Bridge TCP server. It
+      # ends when the Bridge closes the stream or, as EventsBody, when the
+      # server leaves :Running: rackup's WEBrick joins every request thread
+      # before returning, and a read blocked on a quiet worker would hang
+      # Ctrl-C of chi web. The bytes go through unchanged.
+      class ProxyStreamBody
+        def initialize(host:, port:, session_id:, query:, headers:, server_running: -> { true })
+          @client = BridgeClient.new(session_id: session_id, port: port, host: host)
+          @query = query
+          @headers = headers
+          @server_running = server_running
+        end
+
+        def each(&block)
+          # Forward the browser's auto-reconnect cursor: the bridge prefers the
+          # Last-Event-ID header over ?from_seq, and the reconnect URL carries a
+          # stale initial cursor — without this the bridge would replay content
+          # already delivered (duplicate bubbles).
+          @client.stream(query: @query, last_event_id: @headers["HTTP_LAST_EVENT_ID"], running: @server_running, &block)
+        end
+      end
+    end
+  end
+end