tina4ruby 3.12.10 → 3.12.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b3a05320ede8140d3735fd373bfde9772b51c1cb0b8c3a65552863a9cce044a
-  data.tar.gz: 24b318fd87fe6ba03f46333c5edc47621a4d82c1dbd00154ff5d6d1730fefe22
+  metadata.gz: 65d79f819e3ac62c1e8d3447409b8c75530c239db2bb6a7df9066de4104495ed
+  data.tar.gz: d0b0af5dd0e914b880cc64a7b9aca29e6f46de65dcec3104b18e01ad174509b8
 SHA512:
-  metadata.gz: 4d7634856ac4c74a70cfb4f2ae878164ac0718768a113986578a97d8c2cfa24782b34a275f01e06e75a352e62081b4d8dab9b86359943b8a96a4b94bade21a20
-  data.tar.gz: c8791df9abcaa3487648e85a2bd9b98bdfd866138697f4541c261f27d948cd8e302895a8333cdc63287b681143a38e55654a09230030d1e756acbad899e6dd3d
+  metadata.gz: 2e59eac2e37d78d1f7752cd26680338ff404794f6ff23dbe9ab2a1570ce3f458200fd5f488fefb8ef6f5f0b1764aa355def94dbed13a50149df30b4ea798059a
+  data.tar.gz: 7021e0596f5275b4daf0969f0690400e99222fe10f30547b31fc8ee747f266c88086fb577927953813ac53b52dad9d8ce95a7ecb7ae48bfd2c1aa50fa8ff5e47

data/lib/tina4/cli.rb

@@ -265,7 +265,7 @@ module Tina4
 
       db = Tina4.database
       unless db
-        puts "No database configured. Set DATABASE_URL in your .env file."
+        puts "No database configured. Set TINA4_DATABASE_URL in your .env file."
         return
       end
 
@@ -298,7 +298,7 @@ module Tina4
 
       db = Tina4.database
       unless db
-        puts "No database configured. Set DATABASE_URL in your .env file."
+        puts "No database configured. Set TINA4_DATABASE_URL in your .env file."
         return
       end
 
@@ -341,7 +341,7 @@ module Tina4
 
       db = Tina4.database
       unless db
-        puts "No database configured. Set DATABASE_URL in your .env file."
+        puts "No database configured. Set TINA4_DATABASE_URL in your .env file."
         return
       end
 

data/lib/tina4/dev_admin.rb

@@ -369,6 +369,15 @@ module Tina4
         path = env["PATH_INFO"] || "/"
         method = env["REQUEST_METHOD"]
 
+        # Dynamic-path routes can't live in the case-tuple below — match
+        # them up front. /__dev/api/threads/{id}[/messages] is forwarded
+        # verbatim to the Rust agent's /threads/{id}[/messages] surface
+        # (mirrors Python's `_api_threads_sub`).
+        if path.start_with?("/__dev/api/threads/")
+          suffix = path[("/__dev/api".length)..]  # leaves "/threads/{id}[/messages]"
+          return threads_sub_proxy(env, method, suffix)
+        end
+
         case [method, path]
         when ["GET", "/__dev"], ["GET", "/__dev/"]
           serve_dashboard
@@ -382,6 +391,13 @@ module Tina4
           @reload_file = body["file"] || ""
           reload_type = body["type"] || "reload"
           Tina4::Log.info("External reload trigger: #{reload_type}#{@reload_file.empty? ? '' : " (#{@reload_file})"}")
+          # Re-discover so files dropped into src/routes/ register without
+          # a server restart. Idempotent — already-loaded files are skipped.
+          begin
+            Tina4::Router.rescan_routes!
+          rescue StandardError => e
+            Tina4::Log.error("Re-discover on reload failed: #{e.message}")
+          end
           json_response({ ok: true, type: reload_type })
         when ["GET", "/__dev/api/status"]
           json_response(status_payload)
@@ -509,12 +525,21 @@ module Tina4
           tool = (body && body["tool"]) || ""
           json_response(run_tool(tool))
         when ["POST", "/__dev/api/chat"]
-          body = read_json_body(env)
-          message = (body && body["message"]) || ""
-          json_response({
-            reply: "Chat is not yet connected to an AI backend. You said: \"#{message}\"",
-            timestamp: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
-          })
+          # Proxy dev-admin chat to the Rust agent's /chat endpoint.
+          # The SPA POSTs {message, thread_id?, active_file?, settings?}
+          # and expects an SSE stream of `event: status/message/done`
+          # chunks. We forward the JSON body verbatim (active_file rides
+          # along) and pipe upstream bytes back as they arrive. Mirrors
+          # Python's `_api_chat` / `_proxy_to_supervisor` SSE path.
+          body = read_json_body(env) || {}
+          chat_proxy(body)
+        when ["GET", "/__dev/api/threads"]
+          # Parity with Python `_api_threads` (GET → list threads).
+          json_response(proxy_supervisor("/threads", method: "GET", query: env["QUERY_STRING"]))
+        when ["POST", "/__dev/api/threads"]
+          # Parity with Python `_api_threads` (POST → create thread).
+          body = read_json_body(env) || {}
+          json_response(proxy_supervisor("/threads", method: "POST", body: body))
         when ["GET", "/__dev/api/connections"]
           handle_connections_get
         when ["POST", "/__dev/api/connections/test"]
@@ -893,10 +918,13 @@ module Tina4
             key, val = line.split("=", 2)
             key = key.strip
             val = (val || "").strip.gsub(/\A["']|["']\z/, "")
+            # v3.12+ env vars are TINA4_-prefixed; the boot guard refuses to
+            # start with bare DATABASE_URL set, so the dashboard must read
+            # and write the prefixed names.
             case key
-            when "DATABASE_URL" then url = val
-            when "DATABASE_USERNAME" then username = val
-            when "DATABASE_PASSWORD" then password = val.empty? ? "" : "***"
+            when "TINA4_DATABASE_URL" then url = val
+            when "TINA4_DATABASE_USERNAME" then username = val
+            when "TINA4_DATABASE_PASSWORD" then password = val.empty? ? "" : "***"
             end
           end
         end
@@ -954,7 +982,13 @@ module Tina4
         begin
           env_path = File.join(Dir.pwd, ".env")
           lines = File.file?(env_path) ? File.readlines(env_path, chomp: true) : []
-          keys_found = { "DATABASE_URL" => false, "DATABASE_USERNAME" => false, "DATABASE_PASSWORD" => false }
+          # v3.12+ env vars are TINA4_-prefixed; saving bare DATABASE_URL
+          # would trip the framework's legacy-env boot guard on next start.
+          keys_found = {
+            "TINA4_DATABASE_URL" => false,
+            "TINA4_DATABASE_USERNAME" => false,
+            "TINA4_DATABASE_PASSWORD" => false,
+          }
           new_lines = []
           lines.each do |line|
             stripped = line.strip
@@ -964,20 +998,24 @@ module Tina4
             end
             key = stripped.split("=", 2).first.strip
             case key
-            when "DATABASE_URL"
-              new_lines << "DATABASE_URL=#{url}"
-              keys_found["DATABASE_URL"] = true
-            when "DATABASE_USERNAME"
-              new_lines << "DATABASE_USERNAME=#{username}"
-              keys_found["DATABASE_USERNAME"] = true
-            when "DATABASE_PASSWORD"
-              new_lines << "DATABASE_PASSWORD=#{password}"
-              keys_found["DATABASE_PASSWORD"] = true
+            when "TINA4_DATABASE_URL"
+              new_lines << "TINA4_DATABASE_URL=#{url}"
+              keys_found["TINA4_DATABASE_URL"] = true
+            when "TINA4_DATABASE_USERNAME"
+              new_lines << "TINA4_DATABASE_USERNAME=#{username}"
+              keys_found["TINA4_DATABASE_USERNAME"] = true
+            when "TINA4_DATABASE_PASSWORD"
+              new_lines << "TINA4_DATABASE_PASSWORD=#{password}"
+              keys_found["TINA4_DATABASE_PASSWORD"] = true
             else
               new_lines << line
             end
           end
-          values = { "DATABASE_URL" => url, "DATABASE_USERNAME" => username, "DATABASE_PASSWORD" => password }
+          values = {
+            "TINA4_DATABASE_URL" => url,
+            "TINA4_DATABASE_USERNAME" => username,
+            "TINA4_DATABASE_PASSWORD" => password,
+          }
           keys_found.each do |key, found|
             new_lines << "#{key}=#{values[key]}" unless found
           end
@@ -1075,6 +1113,21 @@ module Tina4
                   r["Content-Type"] = "application/json"
                   r.body = JSON.generate(body || {})
                   r
+                when "PATCH"
+                  r = Net::HTTP::Patch.new(uri)
+                  r["Content-Type"] = "application/json"
+                  r.body = JSON.generate(body || {})
+                  r
+                when "PUT"
+                  r = Net::HTTP::Put.new(uri)
+                  r["Content-Type"] = "application/json"
+                  r.body = JSON.generate(body || {})
+                  r
+                when "DELETE"
+                  r = Net::HTTP::Delete.new(uri)
+                  r["Content-Type"] = "application/json"
+                  r.body = JSON.generate(body) if body
+                  r
                 else
                   Net::HTTP::Get.new(uri)
                 end
@@ -1089,6 +1142,85 @@ module Tina4
         end
       end
 
+      # Proxy /__dev/api/threads/{id}[/messages] through to the Rust
+      # agent. Mirrors Python's `_api_threads_sub`: we already stripped
+      # the dev-admin prefix in handle_request, so `suffix` is the path
+      # the agent expects (e.g. `/threads/abc` or `/threads/abc/messages`).
+      # PATCH /threads/{id} (archive/rename) and GET /threads/{id}/messages
+      # are the two shapes the SPA actually fires.
+      def threads_sub_proxy(env, method, suffix)
+        case method.upcase
+        when "GET"
+          json_response(proxy_supervisor(suffix, method: "GET", query: env["QUERY_STRING"]))
+        when "POST"
+          body = read_json_body(env) || {}
+          json_response(proxy_supervisor(suffix, method: "POST", body: body))
+        when "PATCH"
+          body = read_json_body(env) || {}
+          json_response(proxy_supervisor(suffix, method: "PATCH", body: body))
+        when "PUT"
+          body = read_json_body(env) || {}
+          json_response(proxy_supervisor(suffix, method: "PUT", body: body))
+        when "DELETE"
+          body = read_json_body(env)
+          json_response(proxy_supervisor(suffix, method: "DELETE", body: body))
+        else
+          [405, { "content-type" => "application/json; charset=utf-8" },
+           [JSON.generate({ error: "method not allowed" })]]
+        end
+      end
+
+      # POST /chat — proxy the SPA's chat payload to the Rust agent and
+      # pipe the upstream SSE response back to the browser. Active-file
+      # content (when present in the body) rides along verbatim.
+      #
+      # NOTE on streaming: Tina4 Ruby's Rack app does not currently
+      # expose a chunk-by-chunk streaming API to handlers (see
+      # response.rb — `response.stream(&block)` is not yet wired through
+      # the case-tuple dispatcher used here). We do the next best thing:
+      # use Net::HTTP#request_get with a block so we receive upstream
+      # SSE chunks as they arrive, buffer them, and return the assembled
+      # body with the upstream content-type intact. The SPA's
+      # EventSource reader works either way (it parses `data:` lines
+      # regardless of arrival cadence) — the TODO below tracks
+      # converting this to a true streamed Rack body once dev_admin
+      # routes are migrated off the case-tuple dispatcher.
+      def chat_proxy(body)
+        base = supervisor_base
+        begin
+          uri = URI.parse("#{base}/chat")
+          req = Net::HTTP::Post.new(uri)
+          req["Content-Type"] = "application/json"
+          req["Accept"] = "text/event-stream"
+          req.body = JSON.generate(body || {})
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.open_timeout = 2
+          # /chat runs the supervisor → planner → coder loop with one or
+          # more LLM round-trips. Matches Python's 600s budget.
+          http.read_timeout = 600
+          chunks = []
+          upstream_status = 200
+          upstream_ct = "text/event-stream"
+          http.request(req) do |resp|
+            upstream_status = resp.code.to_i
+            upstream_ct = resp["content-type"] || upstream_ct
+            # TODO: stream chunks straight into the Rack response once
+            # dev_admin migrates to response.stream(). For now we
+            # buffer — the SPA's SSE reader still parses correctly.
+            resp.read_body { |chunk| chunks << chunk }
+          end
+          [upstream_status, { "content-type" => upstream_ct }, [chunks.join]]
+        rescue StandardError => e
+          body_str = JSON.generate({
+            error: "supervisor unavailable",
+            detail: e.message,
+            hint: "Run `tina4 serve` (starts the agent server) or set TINA4_SUPERVISOR_URL",
+            supervisor: base
+          })
+          [503, { "content-type" => "application/json; charset=utf-8" }, [body_str]]
+        end
+      end
+
       def execute_proxy(body)
         # Proxy POST /execute to the supervisor at framework_port + 2000.
         # Pass through the response stream as-is (SSE or JSON).

data/lib/tina4/error_overlay.rb

@@ -42,12 +42,20 @@ module Tina4
         exc_type = exception.class.name
         exc_msg  = exception.message
 
+        # Stamp captured_at once when the overlay is generated. Each frame
+        # compares its source file's mtime to this single timestamp and
+        # flags itself stale if the file changed afterwards — protects
+        # against the "browser cached an old overlay, then the AI rewrote
+        # the file" confusion where the displayed source no longer matches
+        # what actually raised the error.
+        captured_at = Time.now.to_f
+
         # ── Stack trace ──
         frames_html = +""
         backtrace = exception.backtrace || []
         backtrace.each do |line|
           file, lineno, method = parse_backtrace_line(line)
-          frames_html << format_frame(file, lineno, method)
+          frames_html << format_frame(file, lineno, method, captured_at: captured_at)
         end
 
         # ── Request info ──
@@ -213,8 +221,9 @@ module Tina4
           "#{rows}</div>"
       end
 
-      def format_frame(filename, lineno, func_name)
+      def format_frame(filename, lineno, func_name, captured_at: 0.0)
         source = (filename && lineno.positive?) ? format_source_block(filename, lineno) : ""
+        stale_badge = stale_file_badge(filename, captured_at)
         "<div style=\"margin-bottom:16px;\">" \
           "<div style=\"margin-bottom:4px;\">" \
           "<span style=\"color:#{BLUE};\">#{esc(filename.to_s)}</span>" \
@@ -222,11 +231,32 @@ module Tina4
           "<span style=\"color:#{YELLOW};\">#{lineno}</span>" \
           "<span style=\"color:#{SUBTEXT};\"> in </span>" \
           "<span style=\"color:#{GREEN};\">#{esc(func_name.to_s)}</span>" \
+          "#{stale_badge}" \
           "</div>" \
           "#{source}" \
           "</div>"
       end
 
+      # When the file on disk was modified AFTER the overlay was generated,
+      # emit a peach pill warning that the visible source may not match what
+      # actually failed. 0.5s margin to avoid filesystem-noise false positives.
+      def stale_file_badge(filename, captured_at)
+        return "" if captured_at.nil? || captured_at <= 0
+        return "" if filename.nil? || filename.to_s.empty?
+        return "" unless File.file?(filename)
+
+        mtime = File.mtime(filename).to_f
+        return "" if mtime <= captured_at + 0.5
+
+        mtime_str = Time.at(mtime).utc.strftime("%H:%M:%S")
+        "<span style=\"background:#{PEACH};color:#{BG};padding:1px 8px;" \
+          "border-radius:3px;font-size:11px;font-weight:700;margin-left:6px;\">" \
+          "FILE MODIFIED @ #{mtime_str} UTC &mdash; source may not match what failed" \
+          "</span>"
+      rescue StandardError
+        ""
+      end
+
       def collapsible(title, content, open_by_default: false)
         open_attr = open_by_default ? " open" : ""
         "<details style=\"margin-top:16px;\"#{open_attr}>" \

data/lib/tina4/feedback.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Tina4
+  # ── Customer feedback widget — server-side plumbing ─────────────────
+  #
+  # Mirrors tina4_python/dev_admin/__init__.py lines 1436-1645. The
+  # widget is for END USERS of a shipped Tina4 app (not developers).
+  # Whitelisted users get a floating bubble that proxies one
+  # conversational turn at a time to the Rust agent's intake endpoint
+  # at <supervisor>/feedback/intake.
+  #
+  # Flow:
+  #   1. Framework middleware injects <script src="/__feedback/widget.js">
+  #      into HTML responses for whitelisted users.
+  #   2. Widget POSTs to /__feedback/api/turn for each conversational turn.
+  #   3. The Ruby handler verifies whitelist + rate-limit, stamps the
+  #      user identity server-side (client cannot fake `sender`), then
+  #      forwards to the Rust agent's /feedback/intake.
+  #   4. Finalised tickets land in .tina4/chat/threads.json with
+  #      kind:"feedback". Developer sees them in the dev admin sidebar.
+  module Feedback
+    RATE_WINDOW = 3600   # 1 hour
+    RATE_MAX = 5         # submissions/turns per user per hour
+
+    # Class-level mutex-guarded hash {user => [timestamps]}. Mirrors the
+    # Python `_FEEDBACK_RATE_LIMIT` dict — process-local, no persistence.
+    @rate_limit = {}
+    @rate_mutex = Mutex.new
+
+    class << self
+      attr_reader :rate_mutex
+
+      # Test/reset helper — clears the in-memory rate-limit table.
+      def reset_rate_limit!
+        @rate_mutex.synchronize { @rate_limit = {} }
+      end
+
+      # Hard master switch.
+      #
+      # Both gates required for the widget to render or the API to
+      # accept submissions:
+      #   - TINA4_ENABLE_FEEDBACK=true (explicit opt-in — off by default)
+      #   - TINA4_FEEDBACK_WHITELIST=... (non-empty list of users)
+      #
+      # Splitting the toggle from the whitelist lets the developer leave
+      # the whitelist intact while pausing the feature in production for
+      # a release (set TINA4_ENABLE_FEEDBACK=false → widget vanishes
+      # everywhere; whitelist comes back online with one env flip).
+      def feedback_enabled?
+        raw = ENV["TINA4_ENABLE_FEEDBACK"].to_s.strip.downcase
+        %w[1 true yes on].include?(raw)
+      end
+
+      # Comma-separated emails / user IDs in env. Empty = no one allowed.
+      def feedback_whitelist
+        return [] unless feedback_enabled?
+        raw = ENV["TINA4_FEEDBACK_WHITELIST"].to_s.strip
+        return [] if raw.empty?
+        raw.split(",").map { |e| e.strip.downcase }.reject(&:empty?)
+      end
+
+      # Best-effort user identity from auth headers.
+      #
+      # Priority:
+      #   1. JWT/Bearer token via Tina4::Auth.authenticate_request —
+      #      pulls email/sub/user_id claim.
+      #   2. TINA4_FEEDBACK_DEV_USER env var override (LOCAL DEV ONLY —
+      #      lets the framework owner test the widget without a full
+      #      auth setup in the test project).
+      def feedback_identify_user(request)
+        begin
+          headers = request_headers(request)
+          payload = Tina4::Auth.authenticate_request(headers)
+          if payload.is_a?(Hash)
+            %w[email sub user_id].each do |key|
+              v = payload[key] || payload[key.to_sym]
+              return v.to_s.strip.downcase if v && !v.to_s.strip.empty?
+            end
+          end
+        rescue StandardError
+          # fall through to dev-user override
+        end
+        dev_user = ENV["TINA4_FEEDBACK_DEV_USER"].to_s.strip
+        return dev_user.downcase unless dev_user.empty?
+        nil
+      end
+
+      # Returns [allowed, identity]. Both halves must be truthy to act.
+      def feedback_is_whitelisted(request)
+        wl = feedback_whitelist
+        return [false, nil] if wl.empty?
+        user = feedback_identify_user(request)
+        return [false, nil] unless user
+        [wl.include?(user), user]
+      end
+
+      # 5 turns/hour per user. Prunes old timestamps lazily.
+      def feedback_rate_limit_ok(user)
+        now = Time.now.to_f
+        @rate_mutex.synchronize do
+          hits = (@rate_limit[user] || []).select { |t| now - t < RATE_WINDOW }
+          if hits.size >= RATE_MAX
+            @rate_limit[user] = hits
+            return false
+          end
+          hits << now
+          @rate_limit[user] = hits
+          true
+        end
+      end
+
+      # Insert the widget <script> into HTML responses for whitelisted users.
+      #
+      # Called from the Rack middleware right before the body is sent.
+      # No-op if:
+      #   - The request is for a /__dev or /__feedback path (developer
+      #     dashboard / widget assets — never inject the customer widget
+      #     on developer pages; the dev admin has its OWN chat trigger).
+      #   - TINA4_ENABLE_FEEDBACK + TINA4_FEEDBACK_WHITELIST not both set
+      #   - Requesting user isn't in the whitelist
+      #   - Response doesn't have a closing </body> tag (fragment, JSON, etc.)
+      # Idempotent: a second call won't double-inject (looks for marker).
+      def inject_feedback_widget(request, html)
+        return html if html.nil? || html.empty?
+        # The customer feedback widget is for END USERS of the shipped
+        # app — injecting on developer-only paths creates a confusing
+        # "two bubbles" UX where the dev chat trigger + customer
+        # feedback bubble sit on top of each other. Hard exclusion at
+        # the framework layer.
+        path = request_path(request)
+        return html if path.start_with?("/__dev") || path.start_with?("/__feedback")
+        allowed, _user = feedback_is_whitelisted(request)
+        return html unless allowed
+        return html if html.include?("data-tina4-feedback")
+        snippet = '<script src="/__feedback/widget.js" data-tina4-feedback></script>'
+        idx = html.rindex("</body>")
+        return html unless idx
+        html[0...idx] + snippet + html[idx..]
+      end
+
+      # POST /__feedback/api/turn — whitelist check + rate-limit + stamp
+      # `sender` server-side, forward to Rust agent
+      # <supervisor>/feedback/intake. Returns a Rack response triple.
+      def handle_turn(env)
+        request = build_request_wrapper(env)
+        allowed, user = feedback_is_whitelisted(request)
+        return json_response({ error: "not authorised for feedback" }, 403) unless allowed
+        unless feedback_rate_limit_ok(user)
+          return json_response({
+            error: "rate limit exceeded",
+            hint: "max #{RATE_MAX} turns per hour"
+          }, 429)
+        end
+
+        body = read_json_body(env)
+        return json_response({ error: "expected JSON body" }, 400) unless body.is_a?(Hash)
+
+        forward_body = body.dup
+        forward_body["sender"] = user  # server-stamped identity
+
+        base = supervisor_base
+        uri = URI.parse("#{base}/feedback/intake")
+        begin
+          req = Net::HTTP::Post.new(uri)
+          req["Content-Type"] = "application/json"
+          req.body = JSON.generate(forward_body)
+          resp = Net::HTTP.start(uri.host, uri.port, open_timeout: 5, read_timeout: 60) { |h| h.request(req) }
+          parsed = begin
+            JSON.parse(resp.body.to_s)
+          rescue JSON::ParserError
+            nil
+          end
+          status_code = resp.code.to_i
+          status_code = 200 if status_code.zero?
+          if parsed
+            json_response(parsed, status_code)
+          else
+            [status_code, { "content-type" => "text/plain; charset=utf-8" }, [resp.body.to_s]]
+          end
+        rescue StandardError => e
+          json_response({
+            error: "agent unreachable",
+            detail: e.message
+          }, 502)
+        end
+      end
+
+      # GET /__feedback/widget.js — serve the bundle at
+      # lib/tina4/public/__feedback/widget.js. Cache-Control: no-cache,
+      # must-revalidate so browsers re-check the bundle on every load.
+      # Without this an old cached bundle (e.g. one that pre-dates the
+      # path-block guard against rendering on /__dev/) can persist for
+      # days and keep painting the bubble on the dev admin even after
+      # the server-side script-tag injection is fixed.
+      def handle_widget_js(_env)
+        js_path = File.expand_path("public/__feedback/widget.js", __dir__)
+        body = if File.file?(js_path)
+                 File.binread(js_path)
+               else
+                 "console.warn('tina4-feedback-widget bundle not built yet');"
+               end
+        headers = {
+          "content-type" => "application/javascript",
+          "cache-control" => "no-cache, must-revalidate",
+          "pragma" => "no-cache"
+        }
+        [200, headers, [body]]
+      end
+
+      # Dispatcher used by RackApp — returns a Rack triple if the path
+      # matches a /__feedback route, else nil.
+      def handle_request(env)
+        path = env["PATH_INFO"] || "/"
+        method = env["REQUEST_METHOD"]
+        case [method, path]
+        when ["GET", "/__feedback/widget.js"]
+          handle_widget_js(env)
+        when ["POST", "/__feedback/api/turn"]
+          handle_turn(env)
+        end
+      end
+
+      private
+
+      # Locate the supervisor (Rust agent) base URL. Mirrors the
+      # Tier 3 helper in dev_admin.rb so both modules agree on the
+      # endpoint resolution rule.
+      def supervisor_base
+        if defined?(Tina4::DevAdmin) && Tina4::DevAdmin.respond_to?(:supervisor_base, true)
+          return Tina4::DevAdmin.send(:supervisor_base)
+        end
+        base = ENV["TINA4_SUPERVISOR_URL"].to_s.strip
+        return base unless base.empty?
+        port = (ENV["TINA4_PORT"] || ENV["PORT"] || "7147").to_i + 2000
+        "http://127.0.0.1:#{port}"
+      end
+
+      def request_path(request)
+        if request.is_a?(Hash)
+          (request["PATH_INFO"] || request[:path] || "").to_s
+        elsif request.respond_to?(:path)
+          request.path.to_s
+        else
+          ""
+        end
+      end
+
+      # Extract Rack-style headers ({"HTTP_AUTHORIZATION" => "..."}) so
+      # Tina4::Auth.authenticate_request can consume them. Accepts a
+      # Rack env hash, a Tina4::Request, or a plain hash of headers.
+      def request_headers(request)
+        if request.is_a?(Hash) && request.keys.any? { |k| k.to_s.start_with?("HTTP_") }
+          return request
+        end
+        if request.respond_to?(:env)
+          return request.env
+        end
+        if request.respond_to?(:headers)
+          h = request.headers || {}
+          # Auth.authenticate_request looks for HTTP_AUTHORIZATION or Authorization
+          rack_like = {}
+          h.each do |k, v|
+            key = k.to_s
+            if key.downcase == "authorization"
+              rack_like["HTTP_AUTHORIZATION"] = v
+            else
+              rack_like[key] = v
+            end
+          end
+          return rack_like
+        end
+        {}
+      end
+
+      # Lightweight request wrapper used by handle_turn so the same
+      # whitelist/identity helpers work whether the caller passes a Rack
+      # env or a Tina4::Request.
+      def build_request_wrapper(env)
+        Struct.new(:path, :env, :headers).new(
+          env["PATH_INFO"] || "/",
+          env,
+          env  # Rack env IS the headers source for Tina4::Auth
+        )
+      end
+
+      def read_json_body(env)
+        input = env["rack.input"]
+        return nil unless input
+        input.rewind if input.respond_to?(:rewind)
+        raw = input.read
+        return nil if raw.nil? || raw.empty?
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def json_response(data, status = 200)
+        [status, { "content-type" => "application/json; charset=utf-8" },
+         [JSON.generate(data)]]
+      end
+    end
+  end
+end