mistri 0.0.3 → 0.1.0

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

@@ -0,0 +1,30 @@
+# 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.
+  Result = Data.define(:message, :status, :pending, :output) do
+    def initialize(message:, status:, pending: [], output: nil)
+      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

data/lib/mistri/session.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+
+module Mistri
+  # The durable record of a run: an append-only log of typed entries over a
+  # pluggable store. Messages replay into provider-ready history; other entry
+  # types (reminders, custom host data) ride alongside without the loop
+  # knowing their shapes.
+  #
+  # A store implements two methods: append(id, entry_hash) and load(id) ->
+  # array of entry hashes in append order. Everything else lives here.
+  class Session
+    attr_reader :id, :store
+
+    def initialize(store:, id: nil)
+      @store = store
+      @id = id || SecureRandom.uuid
+    end
+
+    def append_message(message)
+      append("message", "message" => message.to_h)
+      message
+    end
+
+    # Entries are normalized through JSON at write time, so every store holds
+    # the same canonical shape (string keys, JSON values) and reads behave
+    # identically whether the entry round-tripped a database or stayed in
+    # memory.
+    def append(type, data = {})
+      entry = { "type" => type, "at" => Time.now.utc.iso8601 }.merge(data)
+      @store.append(@id, JSON.parse(JSON.generate(entry)))
+      nil
+    end
+
+    def entries = @store.load(@id)
+
+    # The conversation as the model replays it.
+    def messages = replay.map(&:first)
+
+    # Replay messages paired with the entry index each came from, starting at
+    # the latest compaction boundary. The synthetic summary message carries a
+    # nil index. Compaction places its cuts by these indexes; the full entry
+    # log stays in the store for transcript views.
+    def replay
+      compaction = last_compaction
+      from = compaction ? compaction["kept_from"] : 0
+      pairs = entries.each_with_index.filter_map do |entry, index|
+        [Message.from_h(entry["message"]), index] if index >= from && entry["type"] == "message"
+      end
+      compaction ? [[summary_message(compaction["summary"]), nil], *pairs] : pairs
+    end
+
+    def last_compaction
+      entries.reverse_each.find { |entry| entry["type"] == "compaction" }
+    end
+
+    # Queue a message for a running exchange from any process. The loop folds
+    # pending steers into the transcript at the next turn boundary, so the
+    # model sees them mid-run; one that arrives as the model finishes cleanly
+    # extends the run another turn so it is answered, not left dangling.
+    def steer(text)
+      append("steer", "id" => SecureRandom.uuid, "message" => Message.user(text).to_h)
+    end
+
+    # Steers not yet folded into the transcript, oldest first. The folding
+    # message entry carries the steer id, so consumption is derived from the
+    # log alone and reads the same from every process.
+    def pending_steers
+      folded = entries.filter_map { |entry| entry["steer_id"] }
+      entries.select { |entry| entry["type"] == "steer" && !folded.include?(entry["id"]) }
+    end
+
+    # Record a human's decision on a parked tool call. Decisions are session
+    # entries, so they can be written from any process, days later, with no
+    # agent constructed; the next resume settles them.
+    def approve(call_id, note: nil) = decide(call_id, approved: true, note: note)
+
+    def deny(call_id, note: nil) = decide(call_id, approved: false, note: note)
+
+    # Parked tool calls not yet settled by a tool result, each with its
+    # decision when one has been recorded. Derived from the entry log alone,
+    # so it survives crashes and reads the same from every process.
+    def open_approvals
+      answered = []
+      decisions = {}
+      requests = []
+      entries.each do |entry|
+        case entry["type"]
+        when "message"
+          call_id = entry.dig("message", "tool_call_id")
+          answered << call_id if call_id
+        when "approval_request" then requests << entry["call"]
+        when "approval_decision" then decisions[entry["call_id"]] = entry
+        end
+      end
+      requests.reject { |call| answered.include?(call["id"]) }
+              .map { |call| { call: rebuild_call(call), decision: decisions[call["id"]] } }
+    end
+
+    private
+
+    def summary_message(summary)
+      Message.user("#{Compaction::SUMMARY_PREFACE}\n\n#{summary}")
+    end
+
+    def decide(call_id, approved:, note:)
+      unless open_approvals.any? { |open| open[:call].id == call_id }
+        raise ConfigurationError, "no open approval for #{call_id.inspect}"
+      end
+
+      entry = { "call_id" => call_id, "approved" => approved }
+      entry["note"] = note if note
+      append("approval_decision", entry)
+    end
+
+    def rebuild_call(hash)
+      ToolCall.new(id: hash["id"], name: hash["name"],
+                   arguments: hash["arguments"] || {}, signature: hash["signature"])
+    end
+  end
+end

data/lib/mistri/sinks/action_cable.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Sinks
+    # Broadcasts every event to an Action Cable stream as its to_h shape.
+    # The server resolves lazily at first call, so this file loads without
+    # Rails; pass server: explicitly to use another broadcaster.
+    #
+    #   sink = Mistri::Sinks::ActionCable.new("agent_#{session.id}")
+    #   agent.run(input, &sink)
+    class ActionCable
+      def initialize(stream, server: nil)
+        @stream = stream
+        @server = server
+      end
+
+      def call(event)
+        server.broadcast(@stream, event.to_h)
+      end
+
+      def to_proc = method(:call).to_proc
+
+      private
+
+      def server
+        @server ||= ::ActionCable.server
+      end
+    end
+  end
+end

data/lib/mistri/sinks/coalesced.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Sinks
+    # Wraps any sink and merges bursts of streaming deltas, so a transport
+    # broadcasts at UI speed instead of token speed. Deltas buffer per
+    # content block and flush merged when the interval elapses or any other
+    # event arrives, so ordering is preserved and a turn always ends flushed.
+    #
+    #   sink = Mistri::Sinks::Coalesced.new(
+    #     Mistri::Sinks::ActionCable.new("agent_1"), interval: 0.1,
+    #   )
+    class Coalesced
+      DELTAS = %i[text_delta thinking_delta toolcall_delta].freeze
+
+      def initialize(sink, interval: 0.05)
+        @sink = sink
+        @interval = interval
+        @buffer = nil
+        @flushed_at = now
+      end
+
+      def call(event)
+        unless DELTAS.include?(event.type)
+          flush
+          return @sink.call(event)
+        end
+
+        merge(event)
+        flush if now - @flushed_at >= @interval
+      end
+
+      def to_proc = method(:call).to_proc
+
+      private
+
+      # Merged deltas keep the newest partial, so a consumer that renders
+      # snapshots always renders the latest one.
+      def merge(event)
+        same = @buffer && @buffer.type == event.type &&
+               @buffer.content_index == event.content_index
+        flush if @buffer && !same
+        @buffer = if same
+                    @buffer.with(delta: @buffer.delta.to_s + event.delta.to_s,
+                                 partial: event.partial)
+                  else
+                    event
+                  end
+      end
+
+      def flush
+        pending = @buffer
+        @buffer = nil
+        @flushed_at = now
+        @sink.call(pending) if pending
+      end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/mistri/sinks/sse.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Sinks
+    # Writes events as Server-Sent Events to any IO-like object: a Rack
+    # streaming body, an ActionController::Live stream, a socket. Pure
+    # formatting, the outbound counterpart of the Mistri::SSE decoder.
+    #
+    #   response.headers["Content-Type"] = "text/event-stream"
+    #   agent.run(input, &Mistri::Sinks::SSE.new(response.stream))
+    class SSE
+      def initialize(io)
+        @io = io
+      end
+
+      def call(event)
+        @io.write("event: #{event.type}\ndata: #{JSON.generate(event.to_h)}\n\n")
+        @io.flush if @io.respond_to?(:flush)
+      end
+
+      def to_proc = method(:call).to_proc
+    end
+  end
+end

data/lib/mistri/skill.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Mistri
+  # One expert playbook: a name the model selects by, a description that
+  # earns the selection, and the full body it reads before acting. Build
+  # them from anywhere — Skills.load reads a directory, and a host with
+  # skills in a database constructs these directly.
+  Skill = Data.define(:name, :description, :body) do
+    def initialize(name:, description: "", body: "")
+      raise ConfigurationError, "a skill needs a name" if name.to_s.empty?
+
+      super(name: name.to_s, description: description.to_s, body: body.to_s)
+    end
+  end
+end