tina4ruby 3.13.111 → 3.13.113

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc71b0c82d6e81e389c825ceaea7a266203979977c2215af5efe677c2aabc57d
-  data.tar.gz: 9022b81347b8d00a6c95c6f24edeef3e28d528018a6b8a0afd446b3da877d77e
+  metadata.gz: 964e92e8030ced5a8f4af3934fb9bb7e49df0056d795c5025d5176aed2fa06d2
+  data.tar.gz: 39fa0f71a1b3219bbaa4382f136c1fb69a4f4760436d75339a50d6906ba5a8e0
 SHA512:
-  metadata.gz: 1690d686f268e05963e12078a6097bb02e3c920cef1a0a9e063da928bca30b37a58f507a7ab151be65a64bed2e482b9c61c902b2eb84e14e835c04a5e5b966ec
-  data.tar.gz: 32929f5560047f02f29e0f75a4585704fc6ccdf9b74bcce3abb664c8a5fb5b55ba2c78c930e0449f7e8cba1c700b200c2294e863c70186d76b9cc80520e220a1
+  metadata.gz: 8ceab487af3f411513fb2fbd3a057e15a04560c40ff4268d7663d51ebb62c7b955ab2584d17183e82a0194967ce5baa67f7c9465d62b207a6490aa2741f0aeaf
+  data.tar.gz: 68564196c7aadba28370621f5d613d8700c0a0e5b137ebbed4f871cb7ce6393a4cd535dd531c2455c5db730f3079088805f16d375441d22c390e64db218fcf6d

data/CHANGELOG.md

@@ -6,6 +6,72 @@ number means the same thing everywhere.
 **The authoritative release notes for every shipped version live in the documentation:**
 https://tina4.com/ruby/36-releases
 
+## 3.13.113
+
+Feature: streaming and multimodal AI, plus reusable `Api.stream` primitives
+(ADR-0060).
+
+### Api.stream primitives
+
+- `Tina4::API#stream_bytes(path, ...)` streams the response body as raw
+  chunks in transport order. Pass a block or take an Enumerator.
+- `Tina4::API#stream_lines(path, ...)` yields one UTF-8 String per LF- or
+  CRLF-terminated line; a trailing line without a newline is yielded on EOF;
+  multibyte sequences that split across chunks are buffered.
+- `Tina4::API#stream_sse(path, ...)` frames SSE events into
+  `{data:, event:, id:, retry:}` Hashes; blank line separates events;
+  `:` comment lines are dropped; multi-line `data:` fields are joined with
+  `\n`; the OpenAI `[DONE]` sentinel is delivered as the last event and the
+  iterator ends. Each primitive is layered on the one below it.
+- `Tina4::APIStreamError` (with `#status`) is raised when a stream opens
+  with a non-2xx HTTP status (pre-stream error, no bytes yielded).
+
+### Ai.chat streaming: typed events (breaking)
+
+- `Tina4::Ai.chat(messages, stream: true)` now yields typed event Hashes:
+  `{ type: :text_delta, text: ... }`, `{ type: :tool_call, id:, name:, args: }`,
+  `{ type: :done, finish_reason:, usage: nil }`, or
+  `{ type: :error, message:, code: nil }`. Text deltas fire per chunk;
+  OpenAI `tool_calls` fragments and Anthropic `input_json_delta` fragments
+  are aggregated and emitted as a single `tool_call` event; `done` fires
+  exactly once on the terminal wire signal; `error` replaces `done` on a
+  mid-stream failure. Malformed tool-call arguments JSON raises
+  `Tina4::AiParseError`.
+- The stream path is implemented on top of `Tina4::API#stream_sse`; there is
+  one SSE reader for the framework, shared between `Api` and `Ai`.
+- Migration for 3.13.101–3.13.112 callers: `for chunk in stream` becomes
+  `for event in stream; event[:text] if event[:type] == :text_delta; end`.
+  No shim (feedback_no_aliases, feedback_breaking_changes).
+
+### Ai.chat multimodal content
+
+- `message[:content]` accepts a String OR an Array of parts:
+  `{ type: "text", text: String }` and
+  `{ type: "image", source: "data:<mime>;base64,<payload>" }` or
+  `{ type: "image", source: "https://..." }` (also with symbol keys).
+- Parts are translated per provider before the request is sent:
+  OpenAI / local get `{ type: "image_url", image_url: { url } }`;
+  Anthropic gets `{ type: "image", source: { type: "base64", media_type, data } }`
+  for data URIs or `{ type: "image", source: { type: "url", url } }` for
+  https URLs.
+- Malformed parts (missing `text` or `source`, unknown `type`, non-string
+  values, a `data:` URI without `;base64,`, a plain `http:` URL) raise
+  `Tina4::AiConfigError` before any request is sent.
+
+### Tests
+
+- New `spec/api_stream_contract_spec.rb` with a real local TCP fixture
+  server exercising chunked transport, LF/CRLF line splitting, trailing
+  lines, multibyte-across-chunk-boundary buffering, and every SSE framing
+  case (single/multi-line/named/comment/blank/[DONE]/retry). Verifies the
+  request body reaches the server and that a transport drop raises.
+- Extended `spec/ai_client_contract_spec.rb` with `/stream-openai-tools`,
+  `/stream-anthropic-tools`, `/stream-midstream-drop`, and
+  `/multimodal-echo` cases proving typed events, tool-call aggregation on
+  both providers, one-and-only-one `done`, mid-stream error semantics,
+  no-retry-after-first-event, and the OpenAI/Anthropic body shapes for
+  multimodal parts.
+
 ## 3.13.107
 
 Feature: RBAC role and permission guards (parity across all four frameworks).

data/lib/tina4/ai_client.rb

@@ -3,6 +3,7 @@
 require "json"
 require "net/http"
 require "uri"
+require "openssl"
 
 module Tina4
   class AiError < StandardError; end
@@ -21,16 +22,32 @@ module Tina4
 
   ChatResponse = Struct.new(:text, :model, :usage, :finish_reason, :raw, keyword_init: true)
 
-  # Zero-dependency app-facing AI client (ADR-0053).
+  # Zero-dependency app-facing AI client. ADR-0053 defined the base contract
+  # (chat / complete / embed with a normalised, provider-neutral response
+  # shape); ADR-0060 extended it with typed streaming events and multimodal
+  # content parts. Both live here so the AI surface is a single file.
   class Ai
     PROVIDERS = %w[local openai anthropic].freeze
 
     class << self
-      def chat(messages, model: nil, temperature: nil, max_tokens: nil, stream: false, timeout: nil, provider: nil)
+      # chat(stream: false) still returns a ChatResponse (ADR-0053).
+      # chat(stream: true) returns an Enumerator of typed events (ADR-0060):
+      #
+      #   { type: :text_delta, text: "..." }
+      #   { type: :tool_call,  id: "...", name: "...", args: {...} }
+      #   { type: :done,       finish_reason: "...", usage: {...} | nil }
+      #   { type: :error,      message: "...", code: "..." | nil }
+      #
+      # The typed events replace the ADR-0053 string-only stream shape. That
+      # was a deliberately breaking change (see ADR-0060 §7) so an agent loop
+      # could observe tool_calls and finish_reason without hand-rolled SSE
+      # parsing per app.
+      def chat(messages, model: nil, temperature: nil, max_tokens: nil,
+               stream: false, timeout: nil, provider: nil)
         validate_messages(messages)
         config = resolve_config("chat", model, timeout, provider)
         body = chat_body(config, messages, temperature, max_tokens, stream)
-        return stream_request(config, headers(config), body) if stream
+        return stream_events(config, headers(config), body) if stream
 
         normalize_chat(config[:provider], request_json(config, headers(config), body))
       end
@@ -67,14 +84,61 @@ module Tina4
 
       private
 
+      # ── validation ─────────────────────────────────────────────────────────
+
       def validate_messages(messages)
-        valid = messages.is_a?(Array) && !messages.empty? && messages.all? do |message|
-          message.is_a?(Hash) && %w[system user assistant].include?((message[:role] || message["role"]).to_s) &&
-            (message.key?(:content) ? message[:content] : message["content"]).is_a?(String)
+        unless messages.is_a?(Array) && !messages.empty?
+          raise AiConfigError, "AI messages must be a non-empty list"
+        end
+
+        messages.each do |message|
+          raise AiConfigError, "AI messages must be objects" unless message.is_a?(Hash)
+
+          role = (message[:role] || message["role"]).to_s
+          unless %w[system user assistant].include?(role)
+            raise AiConfigError, "AI messages must contain supported roles"
+          end
+
+          content = message.key?(:content) ? message[:content] : message["content"]
+          validate_content(content)
         end
-        raise AiConfigError, "AI messages must contain supported roles and string content" unless valid
       end
 
+      def validate_content(content)
+        return if content.is_a?(String)
+
+        unless content.is_a?(Array) && !content.empty?
+          raise AiConfigError, "AI message content must be a string or a non-empty list of parts"
+        end
+
+        content.each { |part| validate_content_part(part) }
+      end
+
+      def validate_content_part(part)
+        raise AiConfigError, "AI content parts must be objects" unless part.is_a?(Hash)
+
+        type = (part[:type] || part["type"]).to_s
+        case type
+        when "text"
+          text = part.key?(:text) ? part[:text] : part["text"]
+          raise AiConfigError, "AI text content part must have a string text field" unless text.is_a?(String)
+        when "image"
+          source = part.key?(:source) ? part[:source] : part["source"]
+          raise AiConfigError, "AI image content part must have a string source field" unless source.is_a?(String)
+
+          if source.start_with?("data:")
+            # data:<media_type>;base64,<payload> — enforce the base64 marker
+            raise AiConfigError, "AI image data URI must be base64-encoded" unless source.include?(";base64,")
+          elsif !source.start_with?("https://")
+            raise AiConfigError, "AI image source must be a data:<mime>;base64,<data> URI or an https:// URL"
+          end
+        else
+          raise AiConfigError, "AI content part type must be 'text' or 'image'"
+        end
+      end
+
+      # ── configuration ──────────────────────────────────────────────────────
+
       def number(name, default, minimum)
         value = Float(ENV.fetch(name, default.to_s))
         raise AiConfigError, "#{name} must be at least #{minimum}" if value < minimum
@@ -142,20 +206,80 @@ module Tina4
         result
       end
 
+      # ── request body ───────────────────────────────────────────────────────
+
       def chat_body(config, messages, temperature, max_tokens, stream)
-        normalized = messages.map { |message| { role: (message[:role] || message["role"]).to_s, content: message.key?(:content) ? message[:content] : message["content"] } }
+        provider = config[:provider]
+        normalized = messages.map do |message|
+          role = (message[:role] || message["role"]).to_s
+          content = message.key?(:content) ? message[:content] : message["content"]
+          { role: role, content: translate_content(provider, role, content) }
+        end
         body = { model: config[:model], messages: normalized, stream: stream }
         body[:temperature] = temperature unless temperature.nil?
         body[:max_tokens] = max_tokens unless max_tokens.nil?
-        if config[:provider] == "anthropic"
-          system = normalized.select { |message| message[:role] == "system" }.map { |message| message[:content] }
+        if provider == "anthropic"
+          system_texts = normalized.select { |message| message[:role] == "system" }.map { |message| system_text(message[:content]) }
           body[:messages] = normalized.reject { |message| message[:role] == "system" }
           body[:max_tokens] = max_tokens || 1024
-          body[:system] = system.join("\n\n") unless system.empty?
+          body[:system] = system_texts.join("\n\n") unless system_texts.empty?
         end
         body
       end
 
+      # Anthropic's `system` field is a plain string. If the caller passed a
+      # parts array on a system message, concatenate the text parts (image
+      # parts on the system role are silently dropped — Anthropic rejects them
+      # outright, and validation already ran, so we don't raise a second time).
+      def system_text(content)
+        return content.to_s unless content.is_a?(Array)
+
+        content.select { |part| (part[:type] || part["type"]).to_s == "text" }
+               .map { |part| part[:text] || part["text"] }.join("\n\n")
+      end
+
+      # Translate parts to each provider's native shape. Strings pass through
+      # unchanged. See ADR-0060 §Public surface.
+      def translate_content(provider, role, content)
+        return content if content.is_a?(String)
+        return system_text(content) if provider == "anthropic" && role == "system"
+
+        content.map do |part|
+          type = (part[:type] || part["type"]).to_s
+          case type
+          when "text"
+            { type: "text", text: part[:text] || part["text"] }
+          when "image"
+            translate_image_part(provider, part[:source] || part["source"])
+          end
+        end
+      end
+
+      def translate_image_part(provider, source)
+        if provider == "anthropic"
+          if source.start_with?("data:")
+            media_type, payload = split_data_uri(source)
+            { type: "image", source: { type: "base64", media_type: media_type, data: payload } }
+          else
+            { type: "image", source: { type: "url", url: source } }
+          end
+        else
+          # openai and local both accept the OpenAI image_url shape
+          { type: "image_url", image_url: { url: source } }
+        end
+      end
+
+      def split_data_uri(source)
+        # "data:image/png;base64,<payload>"
+        header, payload = source.split(",", 2)
+        meta = header.to_s.sub(/\Adata:/, "")
+        media_type = meta.split(";").first.to_s
+        media_type = "application/octet-stream" if media_type.empty?
+        [media_type, payload.to_s]
+      end
+
+      # ── non-streaming request path ─────────────────────────────────────────
+
       def http_request(config, deadline, request_headers, body)
         remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
         raise AiTimeoutError, "AI total request timeout expired" unless remaining.positive?
@@ -213,10 +337,13 @@ module Tina4
         sleep(delay) if delay.positive?
       end
 
+      # ── response normalisation ─────────────────────────────────────────────
+
       def normalize_chat(provider, raw)
         if provider == "anthropic"
           parts = raw.fetch("content").select { |item| item.fetch("type", "text") == "text" }.map { |item| item.fetch("text") }
           raise KeyError if parts.empty?
+
           prompt = raw.fetch("usage", {}).fetch("input_tokens", 0).to_i
           completion = raw.fetch("usage", {}).fetch("output_tokens", 0).to_i
           return ChatResponse.new(text: parts.join, model: raw.fetch("model", "").to_s,
@@ -226,6 +353,7 @@ module Tina4
         choice = raw.fetch("choices").fetch(0)
         text = choice.fetch("message").fetch("content")
         raise TypeError unless text.is_a?(String)
+
         usage = raw.fetch("usage", {})
         ChatResponse.new(text: text, model: raw.fetch("model", "").to_s,
                          usage: { prompt_tokens: usage.fetch("prompt_tokens", 0).to_i,
@@ -236,75 +364,209 @@ module Tina4
         raise AiParseError, "AI provider returned a malformed chat response"
       end
 
-      def stream_delta(provider, data)
-        return [true, nil] if data == "[DONE]"
+      # ── streaming (ADR-0060 typed events, built on Api#stream_sse) ─────────
 
-        event = JSON.parse(data)
-        text = if provider == "anthropic"
-                 event["type"] == "content_block_delta" ? event.dig("delta", "text") : nil
-               else
-                 event.dig("choices", 0, "delta", "content")
-               end
-        raise AiParseError, "AI provider returned malformed stream data" unless text.nil? || text.is_a?(String)
+      # Split the resolved provider URL into (origin, request_uri) so we can
+      # hand an Api client the origin and a path -- Api#build_uri concatenates
+      # them without further munging.
+      def split_url(url)
+        uri = URI.parse(url)
+        origin = "#{uri.scheme}://#{uri.host}"
+        origin += ":#{uri.port}" if uri.port
+        [origin, uri.request_uri]
+      end
 
-        [false, text]
-      rescue JSON::ParserError
-        raise AiParseError, "AI provider returned malformed stream data"
+      def stream_events(config, request_headers, body)
+        Enumerator.new do |yielder|
+          stream_pump(config, request_headers, body, yielder)
+        end
       end
 
-      def each_stream_data(response, deadline)
-        buffer = +""
-        response.read_body do |chunk|
-          raise AiTimeoutError, "AI total request timeout expired" if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
-          buffer << chunk
-          while (index = buffer.index("\n"))
-            line = buffer.slice!(0..index).strip
-            yield line.delete_prefix("data:").strip if line.start_with?("data:")
+      def stream_pump(config, request_headers, body, yielder)
+        provider = config[:provider]
+        origin, request_path = split_url(config[:url])
+        api = Tina4::API.new(origin, timeout: config[:total_timeout])
+        stream_headers = request_headers.merge("Accept" => "text/event-stream")
+        request_body_json = JSON.generate(body)
+
+        state = {
+          text_delta_seen: false,
+          done_emitted: false,
+          error_emitted: false,
+          finish_reason: nil,
+          openai_tool_calls: {},         # index -> { id:, name:, args_fragments: [] }
+          anthropic_tool_blocks: {}      # index -> { id:, name:, args_fragments: [] }
+        }
+
+        begin
+          catch(:tina4_ai_stream_end) do
+            api.stream_sse(
+              request_path,
+              method: "POST",
+              body: request_body_json,
+              headers: stream_headers,
+              content_type: "application/json",
+              timeout: config[:total_timeout],
+              connect_timeout: config[:connect_timeout]
+            ) do |sse|
+              handle_sse_event(provider, sse, yielder, state)
+            end
+          end
+
+          # No terminal done/error was emitted -- treat as mid-stream failure.
+          emit_error(yielder, state, "AI provider stream ended before terminal event") unless state[:done_emitted] || state[:error_emitted]
+        rescue Tina4::APIStreamError => e
+          # Pre-stream HTTP error (status arrived before any bytes). Contract:
+          # raise, not error-event. Body is not surfaced (never leak secrets).
+          raise AiHTTPError.new("AI provider returned HTTP #{e.status}", e.status)
+        rescue Net::OpenTimeout
+          raise AiTimeoutError, "AI connection timeout expired"
+        rescue Net::ReadTimeout, Timeout::Error
+          if state[:text_delta_seen]
+            emit_error(yielder, state, "AI total request timeout expired")
+          else
+            raise AiTimeoutError, "AI total request timeout expired"
+          end
+        rescue AiParseError
+          raise
+        rescue SocketError, EOFError, IOError, SystemCallError => e
+          if state[:text_delta_seen]
+            emit_error(yielder, state, "AI transport failed (#{e.class.name})")
+          else
+            raise AiHTTPError, "AI transport failed (#{e.class.name})"
           end
         end
       end
 
-      def stream_request(config, request_headers, body)
-        Enumerator.new do |yielder|
-          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + config[:total_timeout]
-          yielded = false
-          (config[:max_retries] + 1).times do |attempt|
-            begin
-              http, request = http_request(config, deadline, request_headers.merge("Accept" => "text/event-stream"), body)
-              retry_response = false
-              completed = false
-              http.request(request) do |response|
-                status = response.code.to_i
-                unless status.between?(200, 299)
-                  response.read_body { |_chunk| nil }
-                  if (status == 429 || status >= 500) && attempt < config[:max_retries]
-                    retry_delay(response, deadline)
-                    retry_response = true
-                    next
-                  end
-                  raise AiHTTPError.new("AI provider returned HTTP #{status}", status)
-                end
-                each_stream_data(response, deadline) do |data|
-                  completed, text = stream_delta(config[:provider], data)
-                  break if completed
-                  next if text.nil?
-                  yielded = true
-                  yielder << text
-                end
-              end
-              next if retry_response
-              raise AiParseError, "AI provider stream ended before [DONE]" unless completed
-              break
-            rescue Net::OpenTimeout
-              raise AiTimeoutError, "AI connection timeout expired" if yielded || attempt >= config[:max_retries]
-            rescue Net::ReadTimeout, Timeout::Error
-              raise AiTimeoutError, "AI total request timeout expired" if yielded || attempt >= config[:max_retries]
-            rescue SocketError, EOFError, IOError, SystemCallError => e
-              raise AiHTTPError, "AI transport failed (#{e.class.name})" if yielded || attempt >= config[:max_retries]
+      def handle_sse_event(provider, sse, yielder, state)
+        data = sse[:data]
+        return if data.nil?
+
+        if data == "[DONE]"
+          # OpenAI sentinel -- flush any pending tool_calls, then emit :done.
+          flush_openai_tool_calls(yielder, state)
+          emit_done(yielder, state)
+          throw :tina4_ai_stream_end
+        end
+
+        return if data.empty?
+
+        parsed = begin
+          JSON.parse(data)
+        rescue JSON::ParserError
+          raise AiParseError, "AI provider returned malformed stream data"
+        end
+
+        if provider == "anthropic"
+          handle_anthropic_event(parsed, yielder, state)
+        else
+          handle_openai_event(parsed, yielder, state)
+        end
+      end
+
+      def handle_openai_event(parsed, yielder, state)
+        choice = (parsed["choices"] || []).first
+        return unless choice
+
+        delta = choice["delta"] || {}
+        content = delta["content"]
+        if content.is_a?(String) && !content.empty?
+          yielder << { type: :text_delta, text: content }
+          state[:text_delta_seen] = true
+        end
+
+        (delta["tool_calls"] || []).each do |tool_call|
+          index = tool_call["index"] || 0
+          entry = state[:openai_tool_calls][index] ||= { id: nil, name: nil, args_fragments: [] }
+          entry[:id] = tool_call["id"] if tool_call["id"]
+          function = tool_call["function"] || {}
+          entry[:name] = function["name"] if function["name"]
+          entry[:args_fragments] << function["arguments"] if function["arguments"].is_a?(String)
+        end
+
+        reason = choice["finish_reason"]
+        return unless reason
+
+        state[:finish_reason] = reason
+        # The definitive trigger to emit aggregated tool_calls. Some providers
+        # send finish_reason=stop even when tool_calls were streamed, so flush
+        # on any finish_reason -- the flush is a no-op when no calls buffered.
+        flush_openai_tool_calls(yielder, state)
+      end
+
+      def handle_anthropic_event(parsed, yielder, state)
+        case parsed["type"]
+        when "content_block_start"
+          block = parsed["content_block"] || {}
+          if block["type"] == "tool_use"
+            state[:anthropic_tool_blocks][parsed["index"]] = {
+              id: block["id"], name: block["name"], args_fragments: []
+            }
+          end
+        when "content_block_delta"
+          delta = parsed["delta"] || {}
+          case delta["type"]
+          when "text_delta"
+            text = delta["text"]
+            if text.is_a?(String) && !text.empty?
+              yielder << { type: :text_delta, text: text }
+              state[:text_delta_seen] = true
             end
+          when "input_json_delta"
+            entry = state[:anthropic_tool_blocks][parsed["index"]]
+            entry[:args_fragments] << (delta["partial_json"] || "") if entry
           end
+        when "content_block_stop"
+          entry = state[:anthropic_tool_blocks].delete(parsed["index"])
+          emit_anthropic_tool_call(yielder, entry) if entry
+        when "message_delta"
+          reason = (parsed["delta"] || {})["stop_reason"]
+          state[:finish_reason] = reason if reason
+        when "message_stop"
+          emit_done(yielder, state)
+          throw :tina4_ai_stream_end
         end
       end
+
+      def flush_openai_tool_calls(yielder, state)
+        state[:openai_tool_calls].keys.sort.each do |index|
+          entry = state[:openai_tool_calls][index]
+          joined = entry[:args_fragments].join
+          args = parse_tool_args(joined)
+          yielder << { type: :tool_call, id: entry[:id].to_s, name: entry[:name].to_s, args: args }
+        end
+        state[:openai_tool_calls].clear
+      end
+
+      def emit_anthropic_tool_call(yielder, entry)
+        joined = entry[:args_fragments].join
+        args = parse_tool_args(joined)
+        yielder << { type: :tool_call, id: entry[:id].to_s, name: entry[:name].to_s, args: args }
+      end
+
+      def parse_tool_args(joined)
+        return {} if joined.nil? || joined.empty?
+
+        JSON.parse(joined)
+      rescue JSON::ParserError
+        raise AiParseError, "AI provider returned malformed tool_call arguments JSON"
+      end
+
+      def emit_done(yielder, state)
+        return if state[:done_emitted] || state[:error_emitted]
+
+        yielder << { type: :done, finish_reason: state[:finish_reason] || "stop" }
+        state[:done_emitted] = true
+      end
+
+      def emit_error(yielder, state, message, code: nil)
+        return if state[:done_emitted] || state[:error_emitted]
+
+        payload = { type: :error, message: message }
+        payload[:code] = code if code
+        yielder << payload
+        state[:error_emitted] = true
+      end
     end
   end
 end

data/lib/tina4/api.rb

@@ -302,8 +302,182 @@ module Tina4
       end
     end
 
+    # ── Streaming primitives (ADR-0060 / 3.13.113) ─────────────────────────────
+    #
+    # Three cooperating primitives, each layered on the one below:
+    #   * stream_bytes  — raw response body chunks in the order the transport
+    #                     delivers them (no buffering, no framing).
+    #   * stream_lines  — one String per LF- or CRLF-terminated line, decoded as
+    #                     UTF-8. A trailing line without a newline is yielded on
+    #                     EOF. An incomplete UTF-8 sequence at a chunk boundary
+    #                     is buffered across chunks.
+    #   * stream_sse    — SSE-framed events {data:, event:, id:, retry:}. Blank
+    #                     line separates events; ":" comment lines are dropped;
+    #                     multi-line data: fields are joined with "\n"; the
+    #                     OpenAI [DONE] sentinel arrives as the last event
+    #                     (data == "[DONE]") and the iterator ends on the next
+    #                     EOF (the caller decides how to treat it).
+    #
+    # Ruby idiom: pass a block, OR call without a block to get an Enumerator.
+    # Every keyword arg (method:, body:, headers:, content_type:, timeout:,
+    # connect_timeout:) is optional and matches the send_request defaults.
+    # Aborting the iterator (break, StopIteration on Enumerator#next, GC) closes
+    # the underlying socket cleanly — Net::HTTP's block form releases it on any
+    # exit from the block.
+    #
+    # These are the SAME primitives Tina4::Ai.chat(stream: true) uses under the
+    # hood (ADR-0060 rule 5). Application code that streams HTTP anywhere (LLMs,
+    # log tails, event feeds, chunked downloads) reaches for these instead of
+    # hand-rolling a Net::HTTP + line-buffer + SSE-frame reader per app.
+
+    def stream_bytes(path, method: "GET", body: nil, headers: {},
+                     content_type: nil, timeout: nil, connect_timeout: nil, &block)
+      unless block_given?
+        return Enumerator.new do |y|
+          stream_bytes(path, method: method, body: body, headers: headers,
+                       content_type: content_type, timeout: timeout,
+                       connect_timeout: connect_timeout) { |chunk| y << chunk }
+        end
+      end
+      open_stream(path, method, body, headers, content_type, timeout, connect_timeout, &block)
+    end
+
+    def stream_lines(path, method: "GET", body: nil, headers: {},
+                     content_type: nil, timeout: nil, connect_timeout: nil, &block)
+      unless block_given?
+        return Enumerator.new do |y|
+          stream_lines(path, method: method, body: body, headers: headers,
+                       content_type: content_type, timeout: timeout,
+                       connect_timeout: connect_timeout) { |line| y << line }
+        end
+      end
+      buffer = String.new(encoding: Encoding::BINARY)
+      stream_bytes(path, method: method, body: body, headers: headers,
+                   content_type: content_type, timeout: timeout,
+                   connect_timeout: connect_timeout) do |chunk|
+        buffer << chunk.b
+        while (index = buffer.index("\n".b))
+          raw = buffer.byteslice(0, index)
+          raw = raw.byteslice(0, raw.bytesize - 1) if raw.bytesize.positive? && raw.getbyte(raw.bytesize - 1) == 13
+          buffer = buffer.byteslice(index + 1, buffer.bytesize - index - 1) || String.new(encoding: Encoding::BINARY)
+          block.call(decode_utf8(raw))
+        end
+      end
+      block.call(decode_utf8(buffer)) unless buffer.empty?
+    end
+
+    def stream_sse(path, method: "GET", body: nil, headers: {},
+                   content_type: nil, timeout: nil, connect_timeout: nil, &block)
+      unless block_given?
+        return Enumerator.new do |y|
+          stream_sse(path, method: method, body: body, headers: headers,
+                     content_type: content_type, timeout: timeout,
+                     connect_timeout: connect_timeout) { |event| y << event }
+        end
+      end
+      data_parts = []
+      event_name = nil
+      event_id = nil
+      retry_ms = nil
+      dispatch = lambda do
+        return if data_parts.empty? && event_name.nil? && event_id.nil? && retry_ms.nil?
+
+        payload = { data: data_parts.join("\n") }
+        payload[:event] = event_name if event_name
+        payload[:id] = event_id if event_id
+        payload[:retry] = retry_ms if retry_ms
+        block.call(payload)
+        data_parts = []
+        event_name = nil
+        event_id = nil
+        retry_ms = nil
+      end
+      stream_lines(path, method: method, body: body, headers: headers,
+                   content_type: content_type, timeout: timeout,
+                   connect_timeout: connect_timeout) do |line|
+        if line.empty?
+          dispatch.call
+        elsif line.start_with?(":")
+          # comment — ignored per the SSE spec
+        else
+          field, sep, value = line.partition(":")
+          field = line if sep.empty?
+          value = "" if sep.empty?
+          value = value[1..] if value.start_with?(" ")
+          case field
+          when "data"  then data_parts << value
+          when "event" then event_name = value
+          when "id"    then event_id = value
+          when "retry"
+            begin
+              retry_ms = Integer(value)
+            rescue ArgumentError, TypeError
+              retry_ms = nil
+            end
+          end
+        end
+      end
+      dispatch.call
+    end
+
     private
 
+    # Force UTF-8 on a raw line, tolerating a mid-multibyte tail (which
+    # stream_lines already buffered across chunks — the trailing-EOF flush is
+    # the only place an incomplete sequence can slip through, and we mark it
+    # replaceable rather than crash the whole stream).
+    def decode_utf8(bytes)
+      string = bytes.dup.force_encoding(Encoding::UTF_8)
+      string.valid_encoding? ? string : string.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    end
+
+    # Open a single streaming HTTP request and yield body chunks to the block.
+    # Non-2xx responses raise APIStreamError (with the status code); a transport
+    # failure (DNS, connection refused, mid-stream drop) also raises. Net::HTTP's
+    # block form releases the socket when this method returns for any reason —
+    # including a break/StopIteration propagated up from the caller.
+    def open_stream(path, method, body, headers, content_type, timeout, connect_timeout)
+      uri = build_uri(path)
+      request_class = case method.to_s.upcase
+                      when "GET"    then Net::HTTP::Get
+                      when "POST"   then Net::HTTP::Post
+                      when "PUT"    then Net::HTTP::Put
+                      when "PATCH"  then Net::HTTP::Patch
+                      when "DELETE" then Net::HTTP::Delete
+                      when "HEAD"   then Net::HTTP::Head
+                      else raise ArgumentError, "unsupported stream method: #{method}"
+                      end
+      request = request_class.new(uri)
+      apply_headers(request, headers || {})
+      cookie = cookie_header
+      request["Cookie"] = cookie if @cookies_enabled && cookie
+      if body
+        request.body = body.is_a?(String) ? body : JSON.generate(body)
+        request["Content-Type"] = content_type if content_type
+      elsif content_type
+        request["Content-Type"] = content_type
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @verify_ssl == false
+      http.open_timeout = connect_timeout || @timeout
+      http.read_timeout = timeout || @timeout
+      http.write_timeout = (timeout || @timeout) if http.respond_to?(:write_timeout=)
+
+      http.start do |conn|
+        conn.request(request) do |response|
+          status = response.code.to_i
+          unless (200..299).cover?(status)
+            response.read_body { |_chunk| } # drain the error body
+            raise APIStreamError.new("stream returned HTTP #{status}", status)
+          end
+          store_cookies(response.get_fields("Set-Cookie"))
+          response.read_body { |chunk| yield chunk }
+        end
+      end
+    end
+
     def build_uri(path, params = {})
       url = "#{@base_url}#{path}"
       uri = URI.parse(url)
@@ -614,6 +788,21 @@ module Tina4
     end
   end
 
+  # Raised when a streaming request (stream_bytes / stream_lines / stream_sse)
+  # opens successfully but the HTTP status is not 2xx. The buffered `execute`
+  # path folds an error status into an APIResponse; a streaming caller has no
+  # response object to inspect, so the error is raised at the moment the status
+  # is known -- before any bytes are yielded (the pre-stream error contract of
+  # ADR-0060). Carries the status code for the caller to switch on.
+  class APIStreamError < StandardError
+    attr_reader :status
+
+    def initialize(message, status = nil)
+      super(message)
+      @status = status
+    end
+  end
+
   class APIResponse
     attr_reader :status, :body, :headers, :error, :path
 

data/lib/tina4/dev_admin.rb

@@ -407,6 +407,16 @@ module Tina4
           serve_dashboard
         when ["GET", "/__dev/js/tina4-dev-admin.min.js"]
           serve_dev_js
+        when ["GET", "/__dev/toolbar.css"]
+          # tina4stack #115: the injected toolbar's stylesheet, served as an
+          # external asset so the toolbar carries no inline style= and renders
+          # under the default default-src 'self' CSP. Parity with PHP/Python/Node.
+          [200, { "content-type" => "text/css; charset=utf-8" }, [Tina4::RackApp.toolbar_css]]
+        when ["GET", "/__dev/toolbar.js"]
+          # tina4stack #115: the injected toolbar's script (version modal, dash
+          # overlay, WebSocket-primary reloader), served as an external asset so
+          # the toolbar carries no inline <script>/onclick and stays CSP-clean.
+          [200, { "content-type" => "application/javascript; charset=utf-8" }, [Tina4::RackApp.toolbar_js]]
         when ["GET", "/__dev/api/mtime"]
           json_response({ mtime: @reload_mtime || 0, file: @reload_file || "" })
         when ["POST", "/__dev/api/reload"]

data/lib/tina4/rack_app.rb

@@ -915,64 +915,174 @@ module Tina4
       [-1, {}, []]
     end
 
+    # Inject the CSP-clean dev toolbar into HTML responses in dev mode.
+    #
+    # tina4stack #115: the toolbar is CSP-clean - it carries NO inline `style=`,
+    # NO `onclick=` (or any inline handler) and NO inline `<script>` block. All
+    # styling lives in the external `/__dev/toolbar.css` stylesheet and every
+    # interaction is wired via `addEventListener` in the external
+    # `/__dev/toolbar.js`, so the toolbar renders under the framework's default
+    # `default-src 'self'` CSP with no violations. Parity with PHP/Python/Node,
+    # which serve the same external `/__dev/toolbar.{css,js}` assets.
     def inject_dev_overlay(body, request_info, ai_port: false)
       version = Tina4::VERSION
-      # DEVADMIN-DEC-04 (feature 127): the toolbar is injected into EVERY
-      # text/html response (including 404s), so the reflected request
-      # method/path/matched-pattern MUST be HTML-escaped or a crafted path
-      # reflects <script> that runs in the dev-server origin and can then drive
-      # every ungated /__dev mutation route. (Parity with PHP htmlspecialchars
-      # and the Python master html.escape; Ruby was reflecting them raw.)
+      # DEVADMIN-DEC-04 (feature 127): the toolbar rides EVERY text/html response
+      # (including 404s), so the reflected request method/path/matched-pattern
+      # MUST be HTML-escaped or a crafted path reflects <script> that runs in the
+      # dev-server origin and can then drive every ungated /__dev mutation route.
+      # (Parity with PHP htmlspecialchars and the Python master html.escape.)
       method = CGI.escapeHTML(request_info[:method].to_s)
       path = CGI.escapeHTML(request_info[:path].to_s)
       matched_pattern = CGI.escapeHTML(request_info[:matched_pattern].to_s)
-      request_id = Tina4::Log.get_request_id || "-"
+      request_id = CGI.escapeHTML((Tina4::Log.get_request_id || "-").to_s)
       route_count = Tina4::Router.routes.length
+      ruby_version = RUBY_VERSION
 
-      ai_badge = ai_port ? '<span style="background:#7c3aed;color:#fff;font-size:10px;padding:1px 6px;border-radius:3px;font-weight:bold;">AI PORT</span>' : ""
+      # data-reload gates the live reloader in toolbar.js: "1" on the human dev
+      # port, "0" on the AI/stable port (the JS early-returns before starting the
+      # reloader when it is not "1"). Matches Python's render_dev_toolbar.
+      reload = ai_port ? "0" : "1"
+      ai_badge = ai_port ? '<span class="t4-ai-badge">AI PORT</span>' : ""
 
       toolbar = <<~HTML.strip
-        <div id="tina4-dev-toolbar" style="position:fixed;bottom:0;left:0;right:0;background:#333;color:#fff;font-family:monospace;font-size:12px;padding:6px 16px;z-index:99999;display:flex;align-items:center;gap:16px;">
-            #{ai_badge}<span id="tina4-ver-btn" style="color:#d32f2f;font-weight:bold;cursor:pointer;text-decoration:underline dotted;" onclick="tina4VersionModal()" title="Click to check for updates">Tina4 v#{version}</span>
-            <div id="tina4-ver-modal" style="display:none;position:fixed;bottom:3rem;left:1rem;background:#1e1e2e;border:1px solid #d32f2f;border-radius:8px;padding:16px 20px;z-index:100000;min-width:320px;box-shadow:0 8px 32px rgba(0,0,0,0.5);font-family:monospace;font-size:13px;color:#cdd6f4;">
-              <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:12px;">
-                <strong style="color:#89b4fa;">Version Info</strong>
-                <span onclick="document.getElementById('tina4-ver-modal').style.display='none'" style="cursor:pointer;color:#888;">&times;</span>
+        <link rel="stylesheet" href="/__dev/toolbar.css">
+        <div id="tina4-dev-toolbar" data-reload="#{reload}">
+            #{ai_badge}<span id="tina4-ver-btn" title="Click to check for updates">Tina4 v#{version}</span>
+            <div id="tina4-ver-modal">
+              <div class="t4-modal-head">
+                <strong class="t4-modal-title">Version Info</strong>
+                <span id="tina4-ver-close" class="t4-x">&times;</span>
               </div>
-              <div id="tina4-ver-body" style="line-height:1.8;">
-                <div>Current: <strong style="color:#a6e3a1;">v#{version}</strong></div>
-                <div id="tina4-ver-latest" style="color:#888;">Checking for updates...</div>
+              <div id="tina4-ver-body">
+                <div>Current: <strong class="t4-ok">v#{version}</strong></div>
+                <div id="tina4-ver-latest" class="t4-dim">Checking for updates...</div>
               </div>
             </div>
-            <span style="color:#4caf50;">#{method}</span>
+            <span class="t4-green">#{method}</span>
             <span>#{path}</span>
-            <span style="color:#666;">&rarr; #{matched_pattern}</span>
-            <span style="color:#ffeb3b;">req:#{request_id}</span>
-            <span style="color:#90caf9;">#{route_count} routes</span>
-            <span style="color:#888;">Ruby #{RUBY_VERSION}</span>
-            <a href="#" onclick="window.__tina4ToggleOverlay(event)" style="color:#ef9a9a;margin-left:auto;text-decoration:none;cursor:pointer;">Dashboard &#8599;</a>
-            <span onclick="this.parentElement.style.display='none'" style="cursor:pointer;color:#888;margin-left:8px;">&#10005;</span>
+            <span class="t4-arrow">&rarr; #{matched_pattern}</span>
+            <span class="t4-yellow">req:#{request_id}</span>
+            <span class="t4-blue">#{route_count} routes</span>
+            <span class="t4-dim">Ruby #{ruby_version}</span>
+            <a href="#" id="tina4-dash-link" class="t4-dash">Dashboard &#8599;</a>
+            <span id="tina4-bar-close" class="t4-x t4-bar-close">&#10005;</span>
         </div>
-        <script>
-        // Overlay open/toggle helper + auto-restore. Persist the dev-admin
-        // iframe's open/closed state across parent reloads so saving a
-        // file doesn't lose the user's dev-admin context. Cross-framework
-        // parity with PHP / Python / Node — same localStorage key.
-        (function(){
+        <script src="/__dev/toolbar.js"></script>
+      HTML
+
+      if body.include?("</body>")
+        body.sub("</body>", "#{toolbar}\n</body>")
+      else
+        body + "\n" + toolbar
+      end
+    end
+
+    # CSS for the injected dev toolbar. Served as an external stylesheet (see
+    # DevAdmin.handle_request) so the toolbar carries no inline `style=` and
+    # stays CSP-clean under a strict `default-src 'self'`.
+    def self.toolbar_css
+      <<~CSS
+        #tina4-dev-toolbar{position:fixed;bottom:0;left:0;right:0;background:#333;color:#fff;font-family:monospace;font-size:12px;padding:6px 16px;z-index:99999;display:flex;align-items:center;gap:16px}
+        #tina4-dev-toolbar a{text-decoration:none}
+        .t4-ai-badge{background:#7c3aed;color:#fff;font-size:10px;padding:1px 6px;border-radius:3px;font-weight:bold}
+        #tina4-ver-btn{color:#d32f2f;font-weight:bold;cursor:pointer;text-decoration:underline dotted}
+        #tina4-ver-modal{display:none;position:fixed;bottom:3rem;left:1rem;background:#1e1e2e;border:1px solid #d32f2f;border-radius:8px;padding:16px 20px;z-index:100000;min-width:320px;box-shadow:0 8px 32px rgba(0,0,0,.5);font-family:monospace;font-size:13px;color:#cdd6f4}
+        .t4-modal-head{display:flex;justify-content:space-between;align-items:center;margin-bottom:12px}
+        .t4-modal-title{color:#89b4fa}
+        #tina4-ver-body{line-height:1.8}
+        .t4-x{cursor:pointer;color:#888}
+        .t4-bar-close{margin-left:8px}
+        .t4-green{color:#4caf50}
+        .t4-dim{color:#888}
+        .t4-arrow{color:#666}
+        .t4-yellow{color:#ffeb3b}
+        .t4-blue{color:#90caf9}
+        .t4-ok{color:#a6e3a1}
+        .t4-warn{color:#f9e2af}
+        .t4-err{color:#f38ba8}
+        .t4-purple{color:#cba6f7}
+        .t4-link{color:#89b4fa}
+        .t4-code{background:#313244;padding:2px 6px;border-radius:3px}
+        .t4-note{margin-top:6px}
+        .t4-dash{color:#ef9a9a;margin-left:auto;cursor:pointer}
+        #tina4-dev-panel{position:fixed;top:3rem;left:0;right:0;bottom:2rem;z-index:99998;transition:all .2s}
+        #tina4-dev-panel iframe{width:100%;height:100%;border:1px solid #CC342D;border-radius:.5rem;box-shadow:0 8px 32px rgba(0,0,0,.5);background:#0f172a}
+      CSS
+    end
+
+    # JS for the injected dev toolbar - the version-check modal, the dashboard
+    # overlay, and the WebSocket-primary live reloader. Served as an external
+    # script (see DevAdmin.handle_request) so the toolbar carries no inline
+    # handlers or `<script>` and stays CSP-clean. Every handler is wired via
+    # addEventListener; the reloader only starts when the toolbar's `data-reload`
+    # attribute is "1" (reload not suppressed for this request). Mirrors the
+    # Python master's injected client and the PHP external toolbar.js exactly.
+    def self.toolbar_js
+      poll_interval_ms = (ENV["TINA4_DEV_POLL_INTERVAL"] || "3000").to_i
+      poll_interval_ms = 3000 if poll_interval_ms <= 0
+      <<~JS
+        (function () {
+            var bar = document.getElementById('tina4-dev-toolbar');
+            if (!bar) { return; }
+
+            var modal = document.getElementById('tina4-ver-modal');
+            function upToDate(el, latest) {
+                el.className = 't4-ok';
+                el.innerHTML = 'Latest: <strong class="t4-ok">v' + latest + '</strong> &mdash; You are up to date!';
+            }
+            function checkVersion() {
+                if (modal.style.display === 'block') { modal.style.display = 'none'; return; }
+                modal.style.display = 'block';
+                var el = document.getElementById('tina4-ver-latest');
+                el.className = 't4-dim';
+                el.textContent = 'Checking for updates...';
+                fetch('/__dev/api/version-check').then(function (r) { return r.json(); }).then(function (d) {
+                    var latest = d.latest, current = d.current;
+                    if (latest === current) { upToDate(el, latest); return; }
+                    var cP = current.split('.').map(Number), lP = latest.split('.').map(Number);
+                    var isNewer = false, i, c, l;
+                    for (i = 0; i < Math.max(cP.length, lP.length); i++) { c = cP[i] || 0; l = lP[i] || 0; if (l > c) { isNewer = true; break; } if (l < c) { break; } }
+                    var isAhead = false;
+                    if (!isNewer) { for (i = 0; i < Math.max(cP.length, lP.length); i++) { var c2 = cP[i] || 0, l2 = lP[i] || 0; if (c2 > l2) { isAhead = true; break; } if (c2 < l2) { break; } } }
+                    if (isNewer) {
+                        var breaking = (lP[0] !== cP[0] || lP[1] !== cP[1]);
+                        el.className = '';
+                        el.innerHTML = 'Latest: <strong class="t4-warn">v' + latest + '</strong>';
+                        if (breaking) {
+                            el.innerHTML += '<div class="t4-err t4-note">&#9888; Major/minor version change &mdash; check the <a href="https://github.com/tina4stack/tina4-ruby/releases" target="_blank" class="t4-link">changelog</a> for breaking changes before upgrading.</div>';
+                        } else {
+                            el.innerHTML += '<div class="t4-warn t4-note">Patch update available. Run: <code class="t4-code">gem install tina4ruby</code></div>';
+                        }
+                    } else if (isAhead) {
+                        el.className = 't4-purple';
+                        el.innerHTML = 'You are running <strong class="t4-purple">v' + current + '</strong> (ahead of RubyGems <strong>v' + latest + '</strong> &mdash; not yet published).';
+                    } else {
+                        upToDate(el, latest);
+                    }
+                }).catch(function () {
+                    el.className = 't4-err';
+                    el.textContent = 'Could not check for updates (offline?)';
+                });
+            }
+            var verBtn = document.getElementById('tina4-ver-btn');
+            if (verBtn) { verBtn.addEventListener('click', checkVersion); }
+            var verClose = document.getElementById('tina4-ver-close');
+            if (verClose) { verClose.addEventListener('click', function () { modal.style.display = 'none'; }); }
+            var barClose = document.getElementById('tina4-bar-close');
+            if (barClose) { barClose.addEventListener('click', function () { bar.style.display = 'none'; }); }
+
             var STATE_KEY = 'tina4_dev_overlay_open';
             function buildOverlay() {
                 var c = document.createElement('div');
                 c.id = 'tina4-dev-panel';
-                c.style.cssText = 'position:fixed;top:3rem;left:0;right:0;bottom:2rem;z-index:99998;transition:all 0.2s';
                 var f = document.createElement('iframe');
                 f.src = '/__dev';
-                f.style.cssText = 'width:100%;height:100%;border:1px solid #CC342D;border-radius:0.5rem;box-shadow:0 8px 32px rgba(0,0,0,0.5);background:#0f172a';
                 c.appendChild(f);
                 document.body.appendChild(c);
                 return c;
             }
-            window.__tina4ToggleOverlay = function(e) {
-                if (e) e.preventDefault();
+            function toggleOverlay(e) {
+                if (e) { e.preventDefault(); }
                 var p = document.getElementById('tina4-dev-panel');
                 if (p) {
                     var hide = p.style.display !== 'none';
@@ -982,151 +1092,58 @@ module Tina4
                 }
                 buildOverlay();
                 try { localStorage.setItem(STATE_KEY, '1'); } catch (_) {}
-            };
-            function restoreIfOpen() {
-                try {
-                    if (location.pathname.indexOf('/__dev') === 0) return;
-                    if (localStorage.getItem(STATE_KEY) === '1' && !document.getElementById('tina4-dev-panel')) {
-                        buildOverlay();
-                    }
-                } catch (_) {}
-            }
-            if (document.readyState === 'loading') {
-                document.addEventListener('DOMContentLoaded', restoreIfOpen);
-            } else {
-                restoreIfOpen();
             }
-        })();
-        </script>
-        <script>
-        function tina4VersionModal(){
-            var m=document.getElementById('tina4-ver-modal');
-            if(m.style.display==='block'){m.style.display='none';return;}
-            m.style.display='block';
-            var el=document.getElementById('tina4-ver-latest');
-            el.innerHTML='Checking for updates...';
-            el.style.color='#888';
-            fetch('/__dev/api/version-check')
-            .then(function(r){return r.json()})
-            .then(function(d){
-                var latest=d.latest;
-                var current=d.current;
-                if(latest===current){
-                    el.innerHTML='Latest: <strong style="color:#a6e3a1;">v'+latest+'</strong> &mdash; You are up to date!';
-                    el.style.color='#a6e3a1';
-                }else{
-                    var cParts=current.split('.').map(Number);
-                    var lParts=latest.split('.').map(Number);
-                    var isNewer=false;
-                    for(var i=0;i<Math.max(cParts.length,lParts.length);i++){
-                        var c=cParts[i]||0,l=lParts[i]||0;
-                        if(l>c){isNewer=true;break;}
-                        if(l<c)break;
-                    }
-                    var isAhead=false;
-                    if(!isNewer){for(var i=0;i<Math.max(cParts.length,lParts.length);i++){var c2=cParts[i]||0,l2=lParts[i]||0;if(c2>l2){isAhead=true;break;}if(c2<l2)break;}}
-                    if(isNewer){
-                        var breaking=(lParts[0]!==cParts[0]||lParts[1]!==cParts[1]);
-                        el.innerHTML='Latest: <strong style="color:#f9e2af;">v'+latest+'</strong>';
-                        if(breaking){
-                            el.innerHTML+='<div style="color:#f38ba8;margin-top:6px;">&#9888; Major/minor version change &mdash; check the <a href="https://github.com/tina4stack/tina4-ruby/releases" target="_blank" style="color:#89b4fa;">changelog</a> for breaking changes before upgrading.</div>';
-                        }else{
-                            el.innerHTML+='<div style="color:#f9e2af;margin-top:6px;">Patch update available. Run: <code style="background:#313244;padding:2px 6px;border-radius:3px;">gem install tina4ruby</code></div>';
-                        }
-                    }else if(isAhead){
-                        el.innerHTML='You are running <strong style="color:#cba6f7;">v'+current+'</strong> (ahead of RubyGems <strong>v'+latest+'</strong> &mdash; not yet published).';
-                        el.style.color='#cba6f7';
-                    }else{
-                        el.innerHTML='Latest: <strong style="color:#a6e3a1;">v'+latest+'</strong> &mdash; You are up to date!';
-                        el.style.color='#a6e3a1';
-                    }
+            var dash = document.getElementById('tina4-dash-link');
+            if (dash) { dash.addEventListener('click', toggleOverlay); }
+            try {
+                if (location.pathname.indexOf('/__dev') !== 0
+                    && localStorage.getItem(STATE_KEY) === '1'
+                    && !document.getElementById('tina4-dev-panel')) {
+                    buildOverlay();
                 }
-            })
-            .catch(function(){
-                el.innerHTML='Could not check for updates (offline?)';
-                el.style.color='#f38ba8';
-            });
-        }
-        #{ai_port ? "" : dev_reload_client_js}
-        </script>
-      HTML
-
-      if body.include?("</body>")
-        body.sub("</body>", "#{toolbar}\n</body>")
-      else
-        body + "\n" + toolbar
-      end
-    end
-
-    # WebSocket-primary dev reloader injected into HTML pages in debug mode.
-    #
-    # The running server re-imports changed src/ route files in-process and
-    # pushes a {type,file,mtime} message over /__dev_reload — no respawn,
-    # instant refresh. The mtime poll is a FALLBACK only: it is started when
-    # the socket is down and stopped the moment it connects. On a CSS change
-    # the client swaps <link rel=stylesheet> hrefs with a cache-bust query;
-    # any other change does a full location.reload(). The poll seeds its
-    # last-seen mtime to a null sentinel (NOT 0) and reloads whenever the
-    # polled mtime DIFFERS (not just when greater) so the first change after
-    # load isn't swallowed and a counter reset on restart still triggers.
-    # Mirrors the Python master's injected client exactly.
-    def dev_reload_client_js
-      poll_interval_ms = (ENV["TINA4_DEV_POLL_INTERVAL"] || "3000").to_i
-      poll_interval_ms = 3000 if poll_interval_ms <= 0
-      <<~JS
-        (function(){
-            var _t4_css_exts=['.css','.scss'],_t4_debounce=null;
-            var _t4_interval=parseInt('#{poll_interval_ms}')||3000;
-            var _t4_ws=null,_t4_poll_timer=null,_t4_mtime=null;
-            function _t4_apply(d){
-                d=d||{};
-                var f=d.file||'',t=d.type||'';
-                var isCss=t==='css'||_t4_css_exts.some(function(e){return f.endsWith(e)});
-                if(isCss){
-                    var links=document.querySelectorAll('link[rel="stylesheet"]');
-                    links.forEach(function(l){
-                        var href=l.getAttribute('href');
-                        if(href){l.setAttribute('href',href.split('?')[0]+'?_t4='+(d.mtime||Date.now()))}
+            } catch (_) {}
+
+            if (bar.getAttribute('data-reload') !== '1') { return; }
+            var cssExts = ['.css', '.scss'], debounce = null, interval = #{poll_interval_ms};
+            var ws = null, pollTimer = null, mtime = null;
+            function apply(d) {
+                d = d || {};
+                var f = d.file || '', t = d.type || '';
+                var isCss = t === 'css' || cssExts.some(function (e) { return f.endsWith(e); });
+                if (isCss) {
+                    document.querySelectorAll('link[rel="stylesheet"]').forEach(function (l) {
+                        var href = l.getAttribute('href');
+                        if (href) { l.setAttribute('href', href.split('?')[0] + '?_t4=' + (d.mtime || Date.now())); }
                     });
-                }else{
+                } else {
                     location.reload();
                 }
             }
-            function _t4_poll(){
-                fetch('/__dev/api/mtime').then(function(r){return r.json()}).then(function(d){
-                    if(_t4_mtime===null){_t4_mtime=d.mtime;return;}
-                    if(d.mtime!==_t4_mtime){
-                        _t4_mtime=d.mtime;
-                        if(_t4_debounce)clearTimeout(_t4_debounce);
-                        _t4_debounce=setTimeout(function(){_t4_apply(d);},500);
-                    }
-                }).catch(function(){});
-            }
-            function _t4_startPoll(){
-                if(_t4_poll_timer)return;
-                _t4_mtime=null;
-                _t4_poll_timer=setInterval(_t4_poll,_t4_interval);
-            }
-            function _t4_stopPoll(){
-                if(_t4_poll_timer){clearInterval(_t4_poll_timer);_t4_poll_timer=null;}
+            function poll() {
+                fetch('/__dev/api/mtime').then(function (r) { return r.json(); }).then(function (d) {
+                    if (mtime === null) { mtime = d.mtime; return; }
+                    if (d.mtime !== mtime) { mtime = d.mtime; if (debounce) { clearTimeout(debounce); } debounce = setTimeout(function () { apply(d); }, 500); }
+                }).catch(function () {});
             }
-            function _t4_connect(){
-                var url=(location.protocol==='https:'?'wss':'ws')+'://'+location.host+'/__dev_reload';
-                try{_t4_ws=new WebSocket(url);}catch(_){_t4_startPoll();return;}
-                _t4_ws.addEventListener('open',function(){_t4_stopPoll();});
-                _t4_ws.addEventListener('message',function(ev){
-                    var d=null;
-                    try{d=typeof ev.data==='string'?JSON.parse(ev.data):null;}catch(_){}
-                    if(!d)return;
-                    if(d.type==='reload'||d.type==='change'||d.type==='css'){
-                        if(_t4_debounce)clearTimeout(_t4_debounce);
-                        _t4_debounce=setTimeout(function(){_t4_apply(d);},150);
+            function startPoll() { if (pollTimer) { return; } mtime = null; pollTimer = setInterval(poll, interval); }
+            function stopPoll() { if (pollTimer) { clearInterval(pollTimer); pollTimer = null; } }
+            function connect() {
+                var url = (location.protocol === 'https:' ? 'wss' : 'ws') + '://' + location.host + '/__dev_reload';
+                try { ws = new WebSocket(url); } catch (_) { startPoll(); return; }
+                ws.addEventListener('open', function () { stopPoll(); });
+                ws.addEventListener('message', function (ev) {
+                    var d = null;
+                    try { d = typeof ev.data === 'string' ? JSON.parse(ev.data) : null; } catch (_) {}
+                    if (!d) { return; }
+                    if (d.type === 'reload' || d.type === 'change' || d.type === 'css') {
+                        if (debounce) { clearTimeout(debounce); }
+                        debounce = setTimeout(function () { apply(d); }, 150);
                     }
                 });
-                _t4_ws.addEventListener('close',function(){_t4_ws=null;_t4_startPoll();setTimeout(_t4_connect,2000);});
-                _t4_ws.addEventListener('error',function(){try{_t4_ws&&_t4_ws.close();}catch(_){}});
+                ws.addEventListener('close', function () { ws = null; startPoll(); setTimeout(connect, 2000); });
+                ws.addEventListener('error', function () { try { ws && ws.close(); } catch (_) {} });
             }
-            _t4_connect();
+            connect();
         })();
       JS
     end

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.111"
+  VERSION = "3.13.113"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.111
+  version: 3.13.113
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-21 00:00:00.000000000 Z
+date: 2026-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack