mistri 0.0.3 → 0.1.0

data/lib/mistri/providers/fake.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Providers
+    # A scriptable provider: it streams each scripted turn as a well-formed
+    # event sequence and returns the assembled assistant message, so hosts test
+    # agent behavior hermetically while exercising real streaming semantics.
+    #
+    #   provider = Mistri::Providers::Fake.new(turns: [
+    #     { text: "Hello!" },
+    #     { tool_calls: [{ name: "search", arguments: { "q" => "ruby" } }] },
+    #   ])
+    #
+    # A turn may combine :thinking, :text, and :tool_calls, or carry :error to
+    # stream a failed turn. :stop_reason overrides the inferred reason.
+    class Fake
+      MODEL = "fake-1"
+
+      # Every #stream call is recorded here, so a test can assert what the
+      # agent actually sent.
+      attr_reader :requests
+
+      def model = MODEL
+
+      def initialize(turns: [], chunk_size: 12)
+        @turns = turns.map { |turn| turn.transform_keys(&:to_sym) }
+        @chunk_size = [chunk_size, 1].max
+        @requests = []
+      end
+
+      def stream(messages: [], **options, &emit)
+        # Snapshot the array: the loop appends replies to it in place.
+        @requests << { messages: messages.dup, options: }
+        turn = @turns.shift
+        raise ConfigurationError, "fake provider has no scripted turns left" unless turn
+
+        blocks = []
+        emit_event(emit, :start, blocks)
+        return finish_error(turn, blocks, emit) if turn[:error]
+
+        stream_block(:thinking, turn[:thinking], blocks, emit) if turn[:thinking]
+        stream_block(:text, turn[:text], blocks, emit) if turn[:text]
+        Array(turn[:tool_calls]).each_with_index do |call, position|
+          stream_tool_call(call, position, blocks, emit)
+        end
+        finish(turn, blocks, emit)
+      end
+
+      private
+
+      def stream_block(kind, full_text, blocks, emit)
+        index = blocks.size
+        emit_event(emit, :"#{kind}_start", blocks, content_index: index)
+        built = +""
+        full_text.scan(/.{1,#{@chunk_size}}/m) do |chunk|
+          built << chunk
+          emit_event(emit, :"#{kind}_delta", blocks + [build_block(kind, built)],
+                     content_index: index, delta: chunk)
+        end
+        blocks << build_block(kind, full_text)
+        emit_event(emit, :"#{kind}_end", blocks, content_index: index, content: full_text)
+      end
+
+      def build_block(kind, text)
+        kind == :text ? Content::Text.new(text:) : Content::Thinking.new(thinking: text)
+      end
+
+      def stream_tool_call(spec, position, blocks, emit)
+        spec = spec.transform_keys(&:to_sym)
+        call = ToolCall.new(id: spec[:id] || "call_#{position + 1}", name: spec[:name],
+                            arguments: (spec[:arguments] || {}).transform_keys(&:to_s))
+        index = blocks.size
+        emit_event(emit, :toolcall_start, blocks, content_index: index)
+        emit_event(emit, :toolcall_delta, blocks, content_index: index,
+                                                  delta: JSON.generate(call.arguments))
+        blocks << call
+        emit_event(emit, :toolcall_end, blocks, content_index: index, tool_call: call)
+      end
+
+      def finish(turn, blocks, emit)
+        reason = turn[:stop_reason] ||
+                 (blocks.any?(ToolCall) ? StopReason::TOOL_USE : StopReason::STOP)
+        message = assemble(blocks, usage: turn[:usage] || Usage.zero, stop_reason: reason)
+        emit&.call(Event.new(type: :done, reason:, message:))
+        message
+      end
+
+      def finish_error(turn, blocks, emit)
+        error = { "type" => turn.fetch(:error_type, "Error") }
+        error["status"] = turn[:status] if turn[:status]
+        message = assemble(blocks, usage: Usage.zero, stop_reason: StopReason::ERROR,
+                                   error_message: turn[:error], error: error)
+        emit&.call(Event.new(type: :error, reason: StopReason::ERROR, message:,
+                             error_message: turn[:error]))
+        message
+      end
+
+      def assemble(blocks, **meta)
+        Message.assistant(content: blocks, model: MODEL, provider: :fake, **meta)
+      end
+
+      def emit_event(emit, type, blocks, **fields)
+        emit&.call(Event.new(type:, partial: assemble(blocks), **fields))
+      end
+    end
+  end
+end

data/lib/mistri/providers/gemini/assembler.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Providers
+    class Gemini
+      # Folds streamGenerateContent records into the event union. Each record
+      # carries delta parts: plain text extends a text block, thought parts a
+      # thinking block, and a functionCall arrives whole, so its three events
+      # emit back to back. A kind switch closes the open block.
+      #
+      # Thought signatures ride on individual parts and are captured onto the
+      # block they arrived with, verbatim, for replay.
+      class Assembler
+        def initialize(model:)
+          @model = model
+          @blocks = []
+          @current = nil
+          @usage = Usage.zero
+          @finish_reason = nil
+        end
+
+        def feed(record, &)
+          if (error = record["error"])
+            @error = ProviderError.new(error["message"] || "provider error",
+                                       status: error["code"])
+            return
+          end
+
+          candidate = record.dig("candidates", 0) || {}
+          Array(candidate.dig("content", "parts")).each { |part| fold_part(part, &) }
+          @finish_reason = candidate["finishReason"] if candidate["finishReason"]
+          @usage = parse_usage(record["usageMetadata"]) if record["usageMetadata"]
+        end
+
+        # A stream that ended without a finishReason was truncated, not
+        # cancelled: fail it so the loop can treat it as retryable.
+        def finish(&emit)
+          return fail_stream(@error, &emit) if @error
+          return fail_stream("stream ended without a finish reason", &emit) unless @finish_reason
+
+          close_current(&emit)
+          @message = assemble(stop_reason: stop_reason)
+          emit&.call(Event.new(type: :done, reason: @message.stop_reason, message: @message))
+          @message
+        end
+
+        def abort(&)
+          close_current
+          terminal(StopReason::ABORTED, "aborted", &)
+        end
+
+        def fail_stream(reason, &)
+          close_current
+          text = case reason
+                 when ProviderError then "#{reason.class}: #{reason.describe}"
+                 when Exception then "#{reason.class}: #{reason.message}"
+                 else reason.to_s
+                 end
+          terminal(StopReason::ERROR, text, error: ErrorData.for(reason), &)
+        end
+
+        def message = @message ||= finish
+
+        Builder = Struct.new(:kind, :index, :text, :signature)
+
+        private
+
+        def fold_part(part, &)
+          if part.key?("functionCall")
+            fold_function_call(part, &)
+          elsif part.key?("text")
+            fold_text(part, part["thought"] ? :thinking : :text, &)
+          end
+        end
+
+        def fold_text(part, kind, &)
+          close_current(&) if @current && @current.kind != kind
+          unless @current
+            @current = Builder.new(kind, @blocks.size, +"", nil)
+            emit_event(:"#{kind}_start", content_index: @current.index, &)
+          end
+          @current.text << part["text"].to_s
+          @current.signature = part["thoughtSignature"] if part["thoughtSignature"]
+          delta_type = kind == :text ? :text_delta : :thinking_delta
+          emit_event(delta_type, content_index: @current.index, delta: part["text"], &)
+        end
+
+        # A function call arrives complete in one part: start, one delta with
+        # the full arguments, end.
+        def fold_function_call(part, &)
+          close_current(&)
+          call_spec = part["functionCall"] || {}
+          arguments = call_spec["args"].is_a?(Hash) ? call_spec["args"] : {}
+          call = ToolCall.new(id: call_spec["id"] || "call_#{@blocks.size + 1}",
+                              name: call_spec["name"], arguments: arguments,
+                              signature: part["thoughtSignature"])
+          index = @blocks.size
+          emit_event(:toolcall_start, content_index: index, &)
+          emit_event(:toolcall_delta, content_index: index,
+                                      delta: JSON.generate(arguments), &)
+          @blocks << call
+          emit_event(:toolcall_end, content_index: index, tool_call: call, &)
+        end
+
+        def close_current(&)
+          return unless @current
+
+          block = build_current
+          @blocks << block
+          kind = @current.kind
+          index = @current.index
+          @current = nil
+          emit_event(:"#{kind}_end", content_index: index,
+                                     content: kind == :text ? block.text : block.thinking, &)
+        end
+
+        def build_current
+          if @current.kind == :text
+            Content::Text.new(text: @current.text, signature: @current.signature)
+          else
+            Content::Thinking.new(thinking: @current.text, signature: @current.signature)
+          end
+        end
+
+        def stop_reason
+          return StopReason::TOOL_USE if @blocks.any?(ToolCall)
+          return StopReason::LENGTH if @finish_reason == "MAX_TOKENS"
+
+          StopReason::STOP
+        end
+
+        def terminal(reason, text, error: nil, &emit)
+          @message = assemble(stop_reason: reason, error_message: text, error: error)
+          emit&.call(Event.new(type: :error, reason: reason, message: @message,
+                               error_message: text))
+          @message
+        end
+
+        def emit_event(type, **fields, &emit)
+          emit&.call(Event.new(type:, partial: assemble, **fields))
+        end
+
+        def assemble(**meta)
+          blocks = @blocks.dup
+          blocks << build_current if @current
+          Message.assistant(content: blocks, model: @model, provider: :gemini,
+                            usage: @usage, **meta)
+        end
+
+        def parse_usage(raw)
+          prompt = raw["promptTokenCount"].to_i
+          cache_read = raw["cachedContentTokenCount"].to_i
+          reasoning = raw["thoughtsTokenCount"].to_i
+          Usage.new(input: [prompt - cache_read, 0].max,
+                    output: raw["candidatesTokenCount"].to_i + reasoning,
+                    cache_read: cache_read, reasoning: reasoning)
+        end
+      end
+    end
+  end
+end

data/lib/mistri/providers/gemini/serializer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Providers
+    class Gemini
+      # Serializes protocol messages into generateContent contents.
+      #
+      # Wire rules that matter: roles are user and model, consecutive tool
+      # results merge into one user turn of functionResponse parts, and
+      # thought signatures echo back verbatim on the exact part they arrived
+      # with, but only for messages this provider produced; a foreign
+      # signature would be rejected. Thinking summaries are output-only and
+      # never replay.
+      module Serializer
+        module_function
+
+        def contents(history)
+          groups = history.reject(&:system?).chunk_while { |a, b| a.tool? && b.tool? }
+          turns = groups.filter_map do |group|
+            group.first.tool? ? tool_turn(group) : turn(group.first)
+          end
+          merge_user_runs(turns)
+        end
+
+        # A steered run puts a user message right behind tool results, and
+        # both serialize as user turns. Gemini expects turns to alternate, so
+        # consecutive user turns merge into one.
+        def merge_user_runs(turns)
+          turns.chunk_while { |a, b| a[:role] == "user" && b[:role] == "user" }
+               .map do |run|
+            run.length == 1 ? run.first : { role: "user", parts: run.flat_map { |t| t[:parts] } }
+          end
+        end
+
+        def system_instruction(system)
+          return nil if system.nil? || system.empty?
+
+          { parts: [{ text: system }] }
+        end
+
+        def tools(definitions)
+          declarations = definitions.map do |tool|
+            spec = tool.transform_keys(&:to_sym)
+            { name: spec[:name], description: spec[:description],
+              parameters: spec[:input_schema] }
+          end
+          [{ functionDeclarations: declarations }]
+        end
+
+        def turn(msg)
+          parts = msg.assistant? ? assistant_parts(msg) : user_parts(msg)
+          return nil if parts.empty?
+
+          { role: msg.assistant? ? "model" : "user", parts: parts }
+        end
+
+        # Gemini pairs a functionResponse to its call by NAME; a wrong name
+        # silently mismatches, so a missing one fails loudly instead.
+        def tool_turn(group)
+          { role: "user", parts: group.map do |msg|
+            unless msg.tool_name
+              raise SchemaError, "Gemini tool results need tool_name to pair with their call"
+            end
+
+            { functionResponse: { name: msg.tool_name,
+                                  response: { "result" => result_text(msg) } } }
+          end }
+        end
+
+        # Non-text blocks in a tool result have no functionResponse encoding;
+        # note the omission rather than dropping it silently.
+        def result_text(msg)
+          omitted = msg.content.count { |block| !block.is_a?(Content::Text) }
+          text = msg.text.to_s
+          omitted.positive? ? "#{text}\n[#{omitted} non-text block(s) omitted]".strip : text
+        end
+
+        def user_parts(msg)
+          msg.content.map do |block|
+            case block
+            when Content::Text then { text: block.text }
+            when Content::Image
+              { inlineData: { mimeType: block.mime_type, data: block.data } }
+            else
+              raise SchemaError, "cannot serialize #{block.class} for Gemini user input"
+            end
+          end
+        end
+
+        def assistant_parts(msg)
+          own = msg.provider == :gemini
+          msg.content.filter_map do |block|
+            case block
+            when Content::Text then signed({ text: block.text }, block.signature, own)
+            when ToolCall
+              signed({ functionCall: { name: block.name, args: block.arguments } },
+                     block.signature, own)
+            end
+          end
+        end
+
+        def signed(part, signature, own)
+          part[:thoughtSignature] = signature if own && signature
+          part
+        end
+      end
+    end
+  end
+end

data/lib/mistri/providers/gemini.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Providers
+    # The Gemini API (v1beta generateContent), streamed over SSE and
+    # stateless: the full history replays every turn.
+    #
+    # Thinking is deliberately unconstrained: no budget, no level, only
+    # includeThoughts so summaries stream for the UI. The model's own defaults
+    # decide how much to think, and a host override passes through verbatim.
+    # maxOutputTokens is omitted for the same reason: the API defaults to the
+    # model's ceiling.
+    class Gemini
+      DEFAULT_THINKING = { includeThoughts: true }.freeze
+
+      def initialize(api_key:, model: "gemini-2.5-flash",
+                     origin: "https://generativelanguage.googleapis.com",
+                     thinking: DEFAULT_THINKING, **transport_options)
+        @api_key = api_key
+        @model = model
+        @thinking = thinking
+        @transport = Transport.new(origin: origin, **transport_options)
+      end
+
+      attr_reader :model
+
+      def stream(messages:, system: nil, tools: [], signal: nil, **overrides, &emit)
+        model = overrides.fetch(:model, @model)
+        assembler = Gemini::Assembler.new(model: model)
+        body = build_body(messages, system, tools, overrides)
+        path = "/v1beta/models/#{model}:streamGenerateContent?alt=sse"
+        outcome = @transport.stream_post(path, body: body, headers: headers,
+                                               signal: signal) do |record|
+          assembler.feed(record,
+                         &emit)
+        end
+        outcome == :aborted ? assembler.abort(&emit) : assembler.finish(&emit)
+      rescue Error => e
+        assembler.fail_stream(e, &emit)
+      end
+
+      def close = @transport.close
+
+      private
+
+      def build_body(messages, system, tools, overrides)
+        body = { contents: Serializer.contents(messages) }
+        instruction = Serializer.system_instruction(system)
+        body[:systemInstruction] = instruction if instruction
+        body[:tools] = Serializer.tools(tools) if tools.any?
+        config = {}
+        thinking = overrides.fetch(:thinking, @thinking)
+        config[:thinkingConfig] = thinking if thinking
+        # Constrained decoding combines with tools only on 3-series models
+        # (preview); with tools present the task loop's validate-and-fix
+        # pass carries the guarantee instead.
+        if (schema = overrides[:output_schema]) && tools.empty?
+          config[:responseMimeType] = "application/json"
+          config[:responseJsonSchema] = Schema.strict(schema)
+        end
+        body[:generationConfig] = config unless config.empty?
+        body
+      end
+
+      def headers
+        { "x-goog-api-key" => @api_key }
+      end
+    end
+  end
+end
+
+require_relative "gemini/serializer"
+require_relative "gemini/assembler"

data/lib/mistri/providers/openai/assembler.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Providers
+    class OpenAI
+      # Folds the Responses API stream into the event union. Items arrive
+      # sequentially: output_item.added opens a block, typed deltas fill it,
+      # output_item.done closes it with the complete item, whose ids and
+      # encrypted reasoning land in the signature slots for replay.
+      #
+      # Unknown event and item types are skipped by contract.
+      class Assembler
+        def initialize(model:)
+          @model = model
+          @blocks = []
+          @current = nil
+          @usage = Usage.zero
+          @status = nil
+          @incomplete_reason = nil
+        end
+
+        def feed(record, &)
+          case record["type"]
+          when "response.output_item.added" then start_item(record["item"], &)
+          when "response.output_text.delta" then text_delta(record["delta"], &)
+          when "response.reasoning_summary_text.delta" then thinking_delta(record["delta"], &)
+          when "response.function_call_arguments.delta" then arguments_delta(record["delta"], &)
+          when "response.output_item.done" then finish_item(record["item"], &)
+          when "response.completed", "response.incomplete", "response.failed"
+            finish_response(record["response"] || {})
+          when "error" then @error = wire_error(record)
+          end
+        end
+
+        # A stream that ended without a terminal response event was truncated,
+        # not cancelled: fail it so the loop can treat it as retryable.
+        def finish(&emit)
+          return fail_stream(@error, &emit) if @error
+          return fail_stream("stream ended without a terminal event", &emit) unless @status
+
+          @message = assemble(stop_reason: stop_reason)
+          emit&.call(Event.new(type: :done, reason: @message.stop_reason, message: @message))
+          @message
+        end
+
+        def abort(&)
+          terminal(StopReason::ABORTED, "aborted", &)
+        end
+
+        # In-stream failures carry a code; rate limits and server errors must
+        # classify as retryable, not fold into prose.
+        def wire_error(record)
+          message = record["message"] || "provider error"
+          code = record["code"].to_s
+          klass = if code.include?("rate_limit") then RateLimitError
+                  elsif code.include?("server") then ServerError
+                  else ProviderError
+                  end
+          klass.new(message)
+        end
+
+        def fail_stream(reason, &)
+          text = case reason
+                 when ProviderError then "#{reason.class}: #{reason.describe}"
+                 when Exception then "#{reason.class}: #{reason.message}"
+                 else reason.to_s
+                 end
+          terminal(StopReason::ERROR, text, error: ErrorData.for(reason), &)
+        end
+
+        def message = @message ||= finish
+
+        Builder = Struct.new(:kind, :index, :text, :json)
+        KINDS = { "message" => :text, "reasoning" => :thinking,
+                  "function_call" => :toolcall }.freeze
+
+        private
+
+        def start_item(item, &)
+          kind = KINDS[item&.fetch("type", nil)]
+          return unless kind
+
+          @current = Builder.new(kind, @blocks.size, +"", +"")
+          emit_event(:"#{kind}_start", content_index: @current.index, &)
+        end
+
+        def text_delta(delta, &)
+          return unless @current
+
+          @current.text << delta.to_s
+          emit_event(:text_delta, content_index: @current.index, delta: delta, &)
+        end
+
+        def thinking_delta(delta, &)
+          return unless @current
+
+          @current.text << delta.to_s
+          emit_event(:thinking_delta, content_index: @current.index, delta: delta, &)
+        end
+
+        def arguments_delta(delta, &)
+          return unless @current
+
+          @current.json << delta.to_s
+          emit_event(:toolcall_delta, content_index: @current.index, delta: delta, &)
+        end
+
+        # The done item is authoritative: its text, arguments, ids, and
+        # encrypted content replace whatever the deltas accumulated.
+        def finish_item(item, &)
+          kind = KINDS[item&.fetch("type", nil)]
+          return unless kind
+
+          index = @current&.index || @blocks.size
+          block = build_block(kind, item)
+          @blocks << block
+          @current = nil
+          fields = { content_index: index }
+          fields[:tool_call] = block if block.is_a?(ToolCall)
+          unless block.is_a?(ToolCall)
+            fields[:content] = block.respond_to?(:text) ? block.text : block.thinking
+          end
+          emit_event(:"#{kind}_end", **fields.compact, &)
+        end
+
+        def build_block(kind, item)
+          case kind
+          when :text
+            text = Array(item["content"]).filter_map { |part| part["text"] }.join
+            Content::Text.new(text: text, signature: item["id"])
+          when :thinking
+            summary = Array(item["summary"]).filter_map { |part| part["text"] }.join
+            Content::Thinking.new(thinking: summary, signature: JSON.generate(item))
+          when :toolcall
+            ToolCall.new(id: item["call_id"], name: item["name"],
+                         arguments: parse_arguments(item["arguments"]), signature: item["id"])
+          end
+        end
+
+        def parse_arguments(raw)
+          parsed = raw.to_s.strip.empty? ? {} : JSON.parse(raw)
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue JSON::ParserError
+          fallback = PartialJson.parse(raw)
+          fallback.is_a?(Hash) ? fallback : {}
+        end
+
+        def finish_response(response)
+          @status = response["status"] || "completed"
+          @incomplete_reason = response.dig("incomplete_details", "reason")
+          @error = response.dig("error", "message") if @status == "failed"
+          usage = response["usage"]
+          @usage = parse_usage(usage) if usage
+        end
+
+        def stop_reason
+          return StopReason::LENGTH if @incomplete_reason == "max_output_tokens"
+          return StopReason::TOOL_USE if @blocks.any?(ToolCall)
+
+          StopReason::STOP
+        end
+
+        def terminal(reason, text, error: nil, &emit)
+          @message = assemble(stop_reason: reason, error_message: text, error: error)
+          emit&.call(Event.new(type: :error, reason: reason, message: @message,
+                               error_message: text))
+          @message
+        end
+
+        def emit_event(type, **fields, &emit)
+          emit&.call(Event.new(type:, partial: assemble, **fields))
+        end
+
+        def assemble(**meta)
+          blocks = @blocks.dup
+          blocks << partial_block(@current) if @current
+          Message.assistant(content: blocks, model: @model, provider: :openai,
+                            usage: @usage, **meta)
+        end
+
+        def partial_block(builder)
+          case builder.kind
+          when :text then Content::Text.new(text: builder.text)
+          when :thinking then Content::Thinking.new(thinking: builder.text)
+          when :toolcall
+            args = PartialJson.parse(builder.json)
+            ToolCall.new(id: "pending", name: "pending",
+                         arguments: args.is_a?(Hash) ? args : {})
+          end
+        end
+
+        def parse_usage(raw)
+          details = raw["input_tokens_details"] || {}
+          output_details = raw["output_tokens_details"] || {}
+          cache_read = details["cached_tokens"].to_i
+          Usage.new(input: [raw["input_tokens"].to_i - cache_read, 0].max,
+                    output: raw["output_tokens"].to_i, cache_read: cache_read,
+                    reasoning: output_details["reasoning_tokens"].to_i)
+        end
+      end
+    end
+  end
+end