tina4ruby 3.13.112 → 3.13.114

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c0ba91f4e37ef96e557eb291a221cf419821ad59a00bad3e4fe1dbbfaaa5a97
-  data.tar.gz: c54f721f615114967ed5f4e6e86b1c3573da6fb85dcf4fcc9003f0840608b848
+  metadata.gz: a76c2791a9673d8d16cdeece741b3a234561cd1b244b36bcb25fcf87979a35af
+  data.tar.gz: 8c344ec70e43ab6a95ea8622390a50e8473b38857db4113377f1de884bd6d1d6
 SHA512:
-  metadata.gz: 1ada54d7fac14bbfec973040294322d70155c99024c071a4d5a9b558f0ab16d69bf2c57020e92db43ca70a1eeb00099944ddf6d6cf40268ba51f755621426e5c
-  data.tar.gz: b95811c10bf0db5264f304e19ade1f6849f790c4eec98c4106ed2c7a4201380492082fc4a67ef32fd517e0ad58997a7c3888d49e37e79c845e2d2c92c6fa40d4
+  metadata.gz: 0f98f2ca7ecd95280f0290d7b91b712e56fd9186c58732a67d897395bb3be9206308c262b274fe284d79b54aad41ad1d21776b0a7ca7c19ba44b68641c574bdc
+  data.tar.gz: 1acf8361982384c67c1f872838855e1415316f2b8ef396cb3efa2bc9471fb32fa05165d471299f2933e41f31157a1725e6ed4be661632c460d5eb2b246bcad96

data/CHANGELOG.md

@@ -6,6 +6,118 @@ 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.114
+
+Feature: the tool loop closes — `Tina4::Ai.chat` accepts `tools:` and
+`tool_choice:`, and validates tool-result turns in either OpenAI or Anthropic
+form (ADR-0061).
+
+### Send-side additions
+
+- `Tina4::Ai.chat(messages, tools: [...])` translates the neutral tool shape
+  (`{name:, description:, parameters: <JSON-Schema Hash>}`) into each
+  provider's outbound body: OpenAI/local as
+  `[{type: "function", function: {name, description, parameters}}]`;
+  Anthropic as `[{name, description, input_schema}]` (`parameters` renamed).
+  Missing `tools:` omits the field entirely.
+- `Tina4::Ai.chat(..., tool_choice: ...)` accepts `'auto'`, `'none'`,
+  `'required'`, or `{name: 'x'}` (String or Symbol; String or Symbol keys on
+  the Hash). Translation per ADR-0061: `'auto'` → OpenAI `"auto"` / Anthropic
+  `{type: "auto"}`; `'none'` → OpenAI `"none"` / Anthropic OMITS `tools`;
+  `'required'` → OpenAI `"required"` / Anthropic `{type: "any"}`;
+  `{name: 'x'}` → OpenAI `{type: "function", function: {name: "x"}}` /
+  Anthropic `{type: "tool", name: "x"}`.
+- `validate_messages` accepts the two tool-result forms: OpenAI
+  `{role: "tool", tool_call_id:, content:}` and Anthropic
+  `{role: "user", content: [{type: "tool_result", tool_use_id:, content:}]}`.
+  Malformed shapes raise `Tina4::AiConfigError` before any bytes hit the
+  wire.
+- The client normalises whichever form the caller sent to whichever form the
+  configured provider expects, so an agent loop written against `Ai.chat` is
+  provider-neutral. An assistant message with `tool_calls:` and `nil` content
+  now validates too (the OpenAI wire form for a model's tool invocation).
+
+### Tests
+
+`spec/ai_client_contract_spec.rb` grows by 13 fixture-mapped cases across four
+groups: `ai-tools-openai-body-shape`, `ai-tools-anthropic-body-shape`,
+`ai-tools-parameters-passthrough-jsonschema`, `ai-tool-choice-auto`,
+`ai-tool-choice-none`, `ai-tool-choice-required`, `ai-tool-choice-named`,
+`ai-tool-result-openai-form-passthrough`,
+`ai-tool-result-anthropic-form-passthrough`,
+`ai-tool-result-openai-to-anthropic-translation`,
+`ai-tool-result-anthropic-to-openai-translation`,
+`ai-agent-loop-openai-round-trip`, `ai-agent-loop-anthropic-round-trip`. The
+inline `AiContractServer` gains `/tool-echo-openai`, `/tool-echo-anthropic`,
+`/agent-openai`, and `/agent-anthropic` endpoints so the full loop is proven
+against real sockets, no mocks.
+
+## 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,41 @@ 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.
+      #
+      # ADR-0061 adds the SEND half of the agent loop:
+      # - tools: [{name:, description:, parameters:}]  (parameters is JSON-Schema)
+      # - tool_choice: 'auto' | 'none' | 'required' | {name: '...'}
+      # - tool-result turns accepted in either OpenAI or Anthropic form; the
+      #   client normalises to whichever the current provider expects.
+      def chat(messages, model: nil, temperature: nil, max_tokens: nil,
+               stream: false, timeout: nil, provider: nil,
+               tools: nil, tool_choice: nil)
         validate_messages(messages)
+        validate_tools(tools)
+        validate_tool_choice(tool_choice)
         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
+        body = chat_body(config, messages, temperature, max_tokens, stream, tools, tool_choice)
+        return stream_events(config, headers(config), body) if stream
 
         normalize_chat(config[:provider], request_json(config, headers(config), body))
       end
@@ -67,14 +93,121 @@ 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 tool].include?(role)
+            raise AiConfigError, "AI messages must contain supported roles"
+          end
+
+          if role == "tool"
+            # OpenAI-form tool-result message (ADR-0061).
+            tool_call_id = message[:tool_call_id] || message["tool_call_id"]
+            unless tool_call_id.is_a?(String) && !tool_call_id.empty?
+              raise AiConfigError, "AI tool message must have a string tool_call_id"
+            end
+            content = message.key?(:content) ? message[:content] : message["content"]
+            raise AiConfigError, "AI tool message must have a string content" unless content.is_a?(String)
+            next
+          end
+
+          content = message.key?(:content) ? message[:content] : message["content"]
+          # An assistant message carrying tool_calls may have nil content
+          # (that is how the OpenAI wire form encodes the model's tool
+          # invocation). Callers append this before the tool result.
+          if content.nil? && role == "assistant" && (message[:tool_calls] || message["tool_calls"])
+            next
+          end
+
+          validate_content(content)
+        end
+      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
-        raise AiConfigError, "AI messages must contain supported roles and string content" unless valid
+
+        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
+        when "tool_result"
+          # Anthropic-form tool-result part (ADR-0061).
+          tool_use_id = part[:tool_use_id] || part["tool_use_id"]
+          unless tool_use_id.is_a?(String) && !tool_use_id.empty?
+            raise AiConfigError, "AI tool_result part must have a string tool_use_id"
+          end
+          content = part.key?(:content) ? part[:content] : part["content"]
+          raise AiConfigError, "AI tool_result part must have a string content" unless content.is_a?(String)
+        else
+          raise AiConfigError, "AI content part type must be 'text', 'image', or 'tool_result'"
+        end
+      end
+
+      # ── tools + tool_choice validation (ADR-0061) ──────────────────────────
+
+      def validate_tools(tools)
+        return if tools.nil?
+
+        raise AiConfigError, "AI tools must be an array" unless tools.is_a?(Array)
+
+        tools.each do |tool|
+          raise AiConfigError, "Each AI tool must be an object" unless tool.is_a?(Hash)
+
+          name = tool[:name] || tool["name"]
+          raise AiConfigError, "AI tool must have a string name" unless name.is_a?(String) && !name.empty?
+
+          params = tool[:parameters] || tool["parameters"]
+          raise AiConfigError, "AI tool must have a JSON-Schema parameters object" unless params.is_a?(Hash)
+        end
+      end
+
+      def validate_tool_choice(tool_choice)
+        return if tool_choice.nil?
+
+        if tool_choice.is_a?(Hash)
+          name = tool_choice[:name] || tool_choice["name"]
+          return if name.is_a?(String) && !name.empty?
+
+          raise AiConfigError, "AI tool_choice {name:} must have a non-empty string name"
+        end
+
+        value = tool_choice.to_s
+        return if %w[auto none required].include?(value)
+
+        raise AiConfigError, "AI tool_choice must be 'auto', 'none', 'required', or {name: 'x'}"
+      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 +275,208 @@ module Tina4
         result
       end
 
-      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"] } }
+      # ── request body ───────────────────────────────────────────────────────
+
+      def chat_body(config, messages, temperature, max_tokens, stream, tools = nil, tool_choice = nil)
+        provider = config[:provider]
+        normalized = normalize_messages_for_provider(provider, messages)
         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
+        apply_tools(body, provider, tools, tool_choice)
         body
       end
 
+      # Normalise the caller's message list to the provider-native shape.
+      # Tool-result turns are translated between OpenAI form
+      # ({role: 'tool', tool_call_id, content}) and Anthropic form
+      # ({role: 'user', content: [{type: 'tool_result', tool_use_id, content}]})
+      # so the caller's agent loop never has to fork on TINA4_AI_PROVIDER
+      # (ADR-0061). Anthropic-form user messages carrying multiple
+      # tool_result parts fan out to N OpenAI tool messages on the wire.
+      def normalize_messages_for_provider(provider, messages)
+        messages.flat_map { |message| normalize_one_message(provider, message) }
+      end
+
+      def normalize_one_message(provider, message)
+        role = (message[:role] || message["role"]).to_s
+        content = message.key?(:content) ? message[:content] : message["content"]
+
+        if role == "tool"
+          tool_call_id = message[:tool_call_id] || message["tool_call_id"]
+          return translate_openai_tool_message(provider, tool_call_id, content)
+        end
+
+        if role == "assistant" && content.nil?
+          tool_calls = message[:tool_calls] || message["tool_calls"]
+          return [{ role: "assistant", content: nil, tool_calls: tool_calls }]
+        end
+
+        if role == "user" && content.is_a?(Array)
+          tool_result_parts = content.select { |part| part.is_a?(Hash) && content_part_type(part) == "tool_result" }
+          unless tool_result_parts.empty?
+            if tool_result_parts.length != content.length
+              raise AiConfigError, "AI tool_result parts cannot be mixed with other content parts in one message"
+            end
+            return translate_anthropic_tool_results(provider, tool_result_parts)
+          end
+        end
+
+        [{ role: role, content: translate_content(provider, role, content) }]
+      end
+
+      def content_part_type(part)
+        (part[:type] || part["type"]).to_s
+      end
+
+      def translate_openai_tool_message(provider, tool_call_id, content)
+        if provider == "anthropic"
+          [{ role: "user",
+             content: [{ type: "tool_result", tool_use_id: tool_call_id, content: content }] }]
+        else
+          [{ role: "tool", tool_call_id: tool_call_id, content: content }]
+        end
+      end
+
+      def translate_anthropic_tool_results(provider, parts)
+        if provider == "anthropic"
+          [{ role: "user",
+             content: parts.map do |part|
+               { type: "tool_result",
+                 tool_use_id: part[:tool_use_id] || part["tool_use_id"],
+                 content: part[:content] || part["content"] }
+             end }]
+        else
+          parts.map do |part|
+            { role: "tool",
+              tool_call_id: part[:tool_use_id] || part["tool_use_id"],
+              content: part[:content] || part["content"] }
+          end
+        end
+      end
+
+      # ── tools translation (ADR-0061) ───────────────────────────────────────
+
+      def apply_tools(body, provider, tools, tool_choice)
+        return body if tools.nil? && tool_choice.nil?
+
+        # Anthropic has no "none" — the equivalent is to omit tools entirely,
+        # AND we do not emit a tool_choice field either.
+        if provider == "anthropic" && tool_choice_is_string?(tool_choice, "none")
+          return body
+        end
+
+        if tools.is_a?(Array) && !tools.empty?
+          body[:tools] = translate_tools(provider, tools)
+        end
+
+        unless tool_choice.nil?
+          body[:tool_choice] = translate_tool_choice(provider, tool_choice)
+        end
+
+        body
+      end
+
+      def tool_choice_is_string?(tool_choice, value)
+        return false if tool_choice.nil? || tool_choice.is_a?(Hash)
+
+        tool_choice.to_s == value
+      end
+
+      def translate_tools(provider, tools)
+        if provider == "anthropic"
+          tools.map do |tool|
+            { name: tool[:name] || tool["name"],
+              description: tool[:description] || tool["description"],
+              input_schema: tool[:parameters] || tool["parameters"] }
+          end
+        else
+          tools.map do |tool|
+            { type: "function",
+              function: { name: tool[:name] || tool["name"],
+                          description: tool[:description] || tool["description"],
+                          parameters: tool[:parameters] || tool["parameters"] } }
+          end
+        end
+      end
+
+      def translate_tool_choice(provider, tool_choice)
+        if tool_choice.is_a?(Hash)
+          name = tool_choice[:name] || tool_choice["name"]
+          return provider == "anthropic" ? { type: "tool", name: name } : { type: "function", function: { name: name } }
+        end
+
+        value = tool_choice.to_s
+        if provider == "anthropic"
+          case value
+          when "auto"     then { type: "auto" }
+          when "required" then { type: "any" }
+          # "none" was already handled by apply_tools (returns before us).
+          end
+        else
+          value
+        end
+      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 +534,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 +550,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,74 +561,208 @@ 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

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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.112
+  version: 3.13.114
 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