mistri 0.0.3 → 0.2.0

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

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Providers
+    class OpenAI
+      # Serializes protocol messages into Responses API input items.
+      #
+      # Replay pairing is the rule that matters: with store: false the full
+      # history resends every turn, and a reasoning item must return VERBATIM
+      # (its encrypted_content is the model's chain of thought) followed by
+      # the same items it originally preceded. The signature slots carry what
+      # pairing needs: Thinking.signature holds the whole reasoning item,
+      # Text.signature the message item id, ToolCall.signature the
+      # function_call item id.
+      module Serializer
+        module_function
+
+        def input_items(history)
+          history.reject(&:system?).flat_map { |msg| items_for(msg) }
+        end
+
+        def tools(definitions)
+          definitions.map do |tool|
+            spec = tool.transform_keys(&:to_sym)
+            { type: "function", name: spec[:name], description: spec[:description],
+              parameters: spec[:input_schema] }
+          end
+        end
+
+        def items_for(msg)
+          case msg.role
+          when :user then [user_item(msg)]
+          when :tool then [tool_result_item(msg)]
+          when :assistant then assistant_items(msg)
+          else []
+          end
+        end
+
+        def user_item(msg)
+          { role: "user", content: msg.content.map { |block| user_block(block) } }
+        end
+
+        def user_block(block)
+          case block
+          when Content::Text then { type: "input_text", text: block.text }
+          when Content::Image
+            { type: "input_image", image_url: "data:#{block.mime_type};base64,#{block.data}" }
+          else
+            raise SchemaError, "cannot serialize #{block.class} for OpenAI user input"
+          end
+        end
+
+        # Non-text blocks in a tool result have no function_call_output
+        # encoding; note the omission rather than dropping it silently.
+        def tool_result_item(msg)
+          omitted = msg.content.count { |block| !block.is_a?(Content::Text) }
+          text = msg.text.to_s
+          text = "#{text}\n[#{omitted} non-text block(s) omitted]".strip if omitted.positive?
+          { type: "function_call_output", call_id: msg.tool_call_id, output: text }
+        end
+
+        def assistant_items(msg)
+          msg.content.filter_map { |block| assistant_item(block) }
+        end
+
+        def assistant_item(block)
+          case block
+          when Content::Thinking then reasoning_item(block)
+          when Content::Text then message_item(block)
+          when ToolCall then function_call_item(block)
+          end
+        end
+
+        # The reasoning item replays exactly as it arrived or not at all. An
+        # item without encrypted_content triggers a server-side id lookup that
+        # cannot succeed under store: false, so it drops rather than 404s.
+        def reasoning_item(block)
+          return nil unless block.signature
+
+          item = JSON.parse(block.signature)
+          item.is_a?(Hash) && item["encrypted_content"] ? item : nil
+        rescue JSON::ParserError
+          nil
+        end
+
+        def message_item(block)
+          item = { type: "message", role: "assistant",
+                   content: [{ type: "output_text", text: block.text }] }
+          item[:id] = block.signature if block.signature
+          item
+        end
+
+        def function_call_item(block)
+          item = { type: "function_call", call_id: block.id, name: block.name,
+                   arguments: JSON.generate(block.arguments) }
+          item[:id] = block.signature if block.signature
+          item
+        end
+      end
+    end
+  end
+end

data/lib/mistri/providers/openai.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Providers
+    # The OpenAI Responses API, streamed and stateless: store is always false,
+    # the full history replays every turn, and encrypted reasoning items round
+    # trip through the signature slots so nothing depends on server-side
+    # state. Reasoning summaries stream as thinking. max_output_tokens is
+    # deliberately omitted: the API defaults to the model's own ceiling.
+    #
+    # Provider failures fold into the stream as an error turn rather than
+    # raising, matching the Anthropic provider's contract.
+    class OpenAI
+      DEFAULT_REASONING = { summary: "auto" }.freeze
+
+      def initialize(api_key:, model: "gpt-5.5", origin: "https://api.openai.com",
+                     reasoning: DEFAULT_REASONING, **transport_options)
+        @api_key = api_key
+        @model = model
+        @reasoning = reasoning
+        @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 = OpenAI::Assembler.new(model: model)
+        body = build_body(model, messages, system, tools, overrides)
+        outcome = @transport.stream_post("/v1/responses", 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(model, messages, system, tools, overrides)
+        body = {
+          model: model,
+          input: Serializer.input_items(messages),
+          stream: true,
+          store: false,
+          include: ["reasoning.encrypted_content"]
+        }
+        body[:instructions] = system if system && !system.empty?
+        body[:tools] = Serializer.tools(tools) if tools.any?
+        reasoning = overrides.fetch(:reasoning, @reasoning)
+        body[:reasoning] = reasoning if reasoning
+        if (schema = overrides[:output_schema])
+          body[:text] = { format: { type: "json_schema", name: "output", strict: true,
+                                    schema: Schema.strict(schema, all_required: true) } }
+        end
+        body
+      end
+
+      def headers
+        { "Authorization" => "Bearer #{@api_key}" }
+      end
+    end
+  end
+end
+
+require_relative "openai/serializer"
+require_relative "openai/assembler"

data/lib/mistri/reminder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mistri
+  # A periodic reminder for long agentic runs: models drift from their
+  # instructions as turns accumulate, and a short reminder at the tail of
+  # the context, where attention is strongest, pulls them back. It rides
+  # transform_context, so it appears fresh on the wire each time it is due
+  # and never persists to the session.
+  #
+  #   agent = Mistri.agent("claude-opus-4-8", tools: tools,
+  #                        transform_context: Mistri::Reminder.every(
+  #                          3, "Stay on gifting. Verify with tools before claiming.",
+  #                        ))
+  #
+  # Due is counted in completed assistant turns: the first reminder lands
+  # once `after` turns have finished (default: one full interval), then
+  # every `interval` turns.
+  class Reminder
+    def self.every(interval, text, after: nil)
+      new(interval: interval, text: text, after: after)
+    end
+
+    def initialize(interval:, text:, after: nil)
+      @interval = [interval.to_i, 1].max
+      @after = (after || @interval).to_i
+      @body = "<system-reminder>\n#{text}\n</system-reminder>"
+    end
+
+    def call(messages)
+      turns = messages.count(&:assistant?)
+      return messages unless turns >= @after && ((turns - @after) % @interval).zero?
+
+      messages + [Message.user(@body)]
+    end
+  end
+end

data/lib/mistri/result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Mistri
+  # The outcome of a run. A run either finishes, or suspends because a tool
+  # needs a human's approval, or stops on abort or budget. Suspension is a
+  # first-class outcome, not an error: the run returns immediately with
+  # awaiting_approval? true and the pending calls, so nothing blocks waiting
+  # for a decision that may come days later.
+  #
+  # Reads delegate to the final message, so result.text works whether the run
+  # completed or suspended.
+  # output is a task's validated value, nil on plain runs. usage is the
+  # run's own accounting: every persisted turn plus compaction calls, summed
+  # (a resumed run counts from the resume; task sums across its fix passes).
+  Result = Data.define(:message, :status, :pending, :output, :usage) do
+    def initialize(message:, status:, pending: [], output: nil, usage: Usage.zero)
+      super
+    end
+
+    def completed? = status == :completed
+    def awaiting_approval? = status == :awaiting_approval
+    def aborted? = status == :aborted
+    def stopped_by_budget? = status == :budget
+    def errored? = status == :error
+
+    def text = message&.text
+    def stop_reason = message&.stop_reason
+    def error_message = message&.error_message
+    def tool_calls = message ? message.tool_calls : []
+    def to_s = text.to_s
+  end
+end

data/lib/mistri/retry_policy.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Mistri
+  # When a failed turn is worth retrying, and how long to wait. Transient
+  # failures (rate limits, overload, server errors, timeouts, dropped or
+  # truncated streams) retry with jittered exponential backoff, honoring the
+  # provider's retry-after when it sent one. Everything else — auth, invalid
+  # requests, our own bugs — fails fast.
+  #
+  # attempts counts retries, not calls: attempts 3 means up to four requests.
+  class RetryPolicy
+    RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504, 529].freeze
+    RETRYABLE_TYPES = %w[ProviderError RateLimitError OverloadedError ServerError
+                         TruncatedStream].freeze
+
+    attr_reader :attempts, :base, :max_delay
+
+    def initialize(attempts: 3, base: 1.0, max_delay: 30.0)
+      @attempts = attempts
+      @base = base
+      @max_delay = max_delay
+    end
+
+    def retry?(error, attempt)
+      attempt <= attempts && retryable?(error)
+    end
+
+    # error is the ErrorData hash from an errored message. A status decides
+    # when present; otherwise only known-transient types retry, so schema
+    # violations and host bugs never loop.
+    def retryable?(error)
+      return false unless error
+
+      status = error["status"]
+      return RETRYABLE_STATUSES.include?(status) if status
+
+      RETRYABLE_TYPES.include?(error["type"])
+    end
+
+    def delay(attempt, retry_after = nil)
+      return retry_after.clamp(0.0, max_delay) if retry_after
+
+      exponential = base * (2**(attempt - 1))
+      (exponential * rand(0.5..1.0)).clamp(0.0, max_delay)
+    end
+  end
+end

data/lib/mistri/schema.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Mistri
+  # A small builder for tool argument schemas, so a tool declares its inputs
+  # in Ruby instead of hand-writing JSON Schema. It emits the object schema
+  # every provider accepts:
+  #
+  #   Schema.build do
+  #     string :city, "City name", required: true
+  #     string :units, "Temperature units", enum: %w[celsius fahrenheit]
+  #     integer :days, "Forecast length"
+  #   end
+  #
+  # A raw JSON Schema hash is always accepted directly for anything the
+  # builder does not cover, so the DSL is a convenience, never a ceiling.
+  class Schema
+    # instance_exec, not instance_eval: it binds self to the builder without
+    # passing an argument, so a zero-arity lambda works as naturally as a proc.
+    def self.build(&)
+      builder = new
+      builder.instance_exec(&)
+      builder.to_h
+    end
+
+    def initialize
+      @properties = {}
+      @required = []
+    end
+
+    %i[string integer number boolean].each do |type|
+      define_method(type) do |name, description = nil, required: false, enum: nil, **extra|
+        prop = { type: type.to_s }
+        prop[:description] = description if description
+        prop[:enum] = enum if enum
+        @properties[name.to_s] = prop.merge(extra)
+        @required << name.to_s if required
+        nil
+      end
+    end
+
+    def array(name, description = nil, items: { type: "string" }, required: false, **extra)
+      prop = { type: "array", items: items }
+      prop[:description] = description if description
+      @properties[name.to_s] = prop.merge(extra)
+      @required << name.to_s if required
+      nil
+    end
+
+    def object(name, description = nil, required: false, &)
+      prop = self.class.build(&)
+      prop[:description] = description if description
+      @properties[name.to_s] = prop
+      @required << name.to_s if required
+      nil
+    end
+
+    def to_h
+      schema = { type: "object", properties: @properties }
+      schema[:required] = @required unless @required.empty?
+      schema
+    end
+
+    class << self
+      # Violations of a value against the schema subset the harness emits and
+      # providers constrain: types (including type arrays), object properties
+      # with required and additionalProperties: false, array items, enum.
+      # Empty means valid; entries are human-readable, written to be fed back
+      # to a model for one-shot correction.
+      def violations(value, schema, path = "$")
+        spec = schema.transform_keys(&:to_s)
+        mismatch = type_violation(value, spec, path)
+        return [mismatch] if mismatch
+
+        errors = []
+        if (enum = spec["enum"]) && !enum.include?(value)
+          errors << "#{path} must be one of: #{enum.join(", ")}"
+        end
+        case value
+        when Hash then errors.concat(object_violations(value, spec, path))
+        when Array then errors.concat(array_violations(value, spec, path))
+        end
+        errors
+      end
+
+      # Prepares a schema for constrained decoding: every object gains
+      # additionalProperties: false (Anthropic and OpenAI both demand it),
+      # and all_required marks every property required (OpenAI strict mode's
+      # rule). String keys throughout, ready for the wire.
+      def strict(schema, all_required: false)
+        spec = schema.transform_keys(&:to_s)
+        out = spec.dup
+        if spec["type"] == "object" || spec.key?("properties")
+          props = (spec["properties"] || {}).to_h do |key, member|
+            [key.to_s, strict(member, all_required: all_required)]
+          end
+          out["properties"] = props
+          out["additionalProperties"] = false
+          out["required"] = all_required ? props.keys : Array(spec["required"]).map(&:to_s)
+        end
+        if spec["items"].is_a?(Hash)
+          out["items"] =
+            strict(spec["items"], all_required: all_required)
+        end
+        out
+      end
+
+      TYPES = {
+        "object" => ->(v) { v.is_a?(Hash) }, "array" => ->(v) { v.is_a?(Array) },
+        "string" => ->(v) { v.is_a?(String) }, "integer" => ->(v) { v.is_a?(Integer) },
+        "number" => ->(v) { v.is_a?(Numeric) }, "boolean" => ->(v) { [true, false].include?(v) },
+        "null" => lambda(&:nil?)
+      }.freeze
+
+      private
+
+      def type_violation(value, spec, path)
+        names = Array(spec["type"]).map(&:to_s)
+        return nil if names.empty?
+        return nil if names.any? { |name| TYPES.fetch(name, ->(_) { true }).call(value) }
+
+        "#{path} must be #{names.join(" or ")}, got #{json_type(value)}"
+      end
+
+      def object_violations(value, spec, path)
+        props = (spec["properties"] || {}).transform_keys(&:to_s)
+        errors = Array(spec["required"]).map(&:to_s).filter_map do |key|
+          "#{path}.#{key} is required" unless value.key?(key)
+        end
+        value.each do |key, member|
+          if (member_schema = props[key.to_s])
+            errors.concat(violations(member, member_schema, "#{path}.#{key}"))
+          elsif spec["additionalProperties"] == false
+            errors << "#{path}.#{key} is not allowed"
+          end
+        end
+        errors
+      end
+
+      def array_violations(value, spec, path)
+        items = spec["items"]
+        return [] unless items.is_a?(Hash)
+
+        value.each_with_index.flat_map do |member, index|
+          violations(member, items, "#{path}[#{index}]")
+        end
+      end
+
+      def json_type(value)
+        case value
+        when Hash then "object"
+        when Array then "array"
+        when String then "string"
+        when Integer then "integer"
+        when Numeric then "number"
+        when true, false then "boolean"
+        when nil then "null"
+        else value.class.name
+        end
+      end
+    end
+  end
+end