mistri 0.0.2 → 0.1.0

data/lib/mistri/content.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Mistri
+  # Typed content blocks: what a message is made of. Text and thinking on
+  # assistant turns, text and images on user and tool-result turns, tool calls
+  # alongside them. Blocks are immutable values that compare by content,
+  # pattern-match, and round-trip through #to_h / Content.from_h, so sessions
+  # replay without the loop knowing block shapes.
+  module Content
+    # String#to_s returns self, so a caller's mutable buffer would alias into an
+    # immutable block; blocks own a frozen copy instead.
+    def self.freeze_string(value)
+      s = value.to_s
+      s.frozen? ? s : s.dup.freeze
+    end
+
+    # `signature` carries opaque provider metadata that must round-trip, such as
+    # the OpenAI Responses message id and output phase.
+    Text = Data.define(:text, :signature) do
+      def initialize(text:, signature: nil) = super(text: Content.freeze_string(text), signature:)
+
+      def type = :text
+
+      def to_h = { type: :text, text:, signature: }.compact
+    end
+
+    # A model's reasoning. `signature` is the opaque payload a provider needs to
+    # replay the block on a later turn; `redacted` marks reasoning a safety
+    # filter hid, leaving only the signature.
+    Thinking = Data.define(:thinking, :signature, :redacted) do
+      def initialize(thinking:, signature: nil, redacted: false)
+        super(thinking: Content.freeze_string(thinking), signature:, redacted:)
+      end
+
+      def type = :thinking
+
+      def redacted? = redacted
+
+      def to_h
+        h = { type: :thinking, thinking: }
+        h[:signature] = signature if signature
+        h[:redacted] = true if redacted
+        h
+      end
+    end
+
+    # A base64-encoded image with its MIME type.
+    Image = Data.define(:data, :mime_type) do
+      # Frozen at the pack site so the initializer's ownership check skips a
+      # second copy of what can be a multi-megabyte payload.
+      def self.from_bytes(bytes, mime_type:) = new(data: [bytes.b].pack("m0").freeze, mime_type:)
+
+      def initialize(data:, mime_type:)
+        super(data: Content.freeze_string(data), mime_type: Content.freeze_string(mime_type))
+      end
+
+      def type = :image
+
+      def bytes = data.unpack1("m0")
+
+      def to_h = { type: :image, data:, mime_type: }
+    end
+
+    # Coerce a value into a list of blocks: nil becomes none, a String becomes
+    # one Text block, blocks pass through, arrays may mix all of these.
+    def self.wrap(content)
+      Array(content).map do |block|
+        block.respond_to?(:type) ? block : Text.new(text: block.to_s)
+      end
+    end
+
+    # The inverse of #to_h, used when a session is read back. Keys may be
+    # symbols or, after a JSON round-trip, strings.
+    def self.from_h(hash)
+      h = hash.transform_keys(&:to_s)
+      case h["type"].to_s
+      when "text" then Text.new(text: h["text"], signature: h["signature"])
+      when "thinking"
+        Thinking.new(thinking: h["thinking"], signature: h["signature"],
+                     redacted: h.fetch("redacted", false))
+      when "image" then Image.new(data: h["data"], mime_type: h["mime_type"])
+      when "tool_call"
+        ToolCall.new(id: h["id"], name: h["name"], arguments: h["arguments"] || {},
+                     signature: h["signature"])
+      else raise ArgumentError, "unknown content block type #{h["type"].inspect}"
+      end
+    end
+  end
+end

data/lib/mistri/edit.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module Mistri
+  # Pure fuzzy text replacement: no files, no I/O. This is the string core that
+  # a workspace-backed edit tool calls, so it works the same against a database
+  # row as against a file on disk.
+  #
+  # Each edit's old text must match one region and only one, so an edit can
+  # never silently change the wrong place. Matching relaxes in two steps: an
+  # exact substring first, then a whitespace-tolerant line match that forgives
+  # the indentation and trailing-space drift models introduce when they
+  # reproduce code they read. Unmatched regions keep their exact bytes,
+  # including the file's original line endings.
+  module Edit
+    Match = Struct.new(:start, :finish, :replacement, :edit_index)
+    Result = Data.define(:content, :count)
+
+    module_function
+
+    # The model-facing single edit: replace old_string once (unique match
+    # required) or everywhere with replace_all. Returns a Result carrying the
+    # new content and how many places changed. The replacement adapts to the
+    # document's newline style, so an LF-authored new_string dropped into a
+    # CRLF document does not mix endings.
+    def replace(content, old_string, new_string, replace_all: false)
+      old = old_string.to_s
+      raise EditError, "old_string is empty" if old.empty?
+
+      new = adapt_newlines(content, new_string.to_s)
+      return replace_every(content, old, new) if replace_all
+
+      match = locate(content, { old: old, new: new, index: 0 })
+      changed = content[0...match.start] + match.replacement + content[match.finish..]
+      raise EditError, "the edit changed nothing" if changed == content
+
+      Result.new(content: changed, count: 1)
+    end
+
+    # Apply edits (each {old:, new:}, string or symbol keys) to content and
+    # return the new content. Raises EditError when an edit matches nothing,
+    # matches more than once, overlaps another, or changes nothing.
+    def apply(content, edits)
+      normalized = edits.each_with_index.map { |edit, i| normalize(edit, i) }
+      matches = normalized.map { |edit| locate(content, edit) }.sort_by(&:start)
+      reject_overlaps(matches)
+
+      result = matches.reverse.reduce(content) do |text, match|
+        text[0...match.start] + match.replacement + text[match.finish..]
+      end
+      raise EditError, "the edits changed nothing" if result == content
+
+      result
+    end
+
+    def normalize(edit, index)
+      edit = edit.transform_keys(&:to_sym)
+      old = edit[:old].to_s
+      raise EditError, "edits[#{index}] has empty old text" if old.empty?
+
+      { old: old, new: edit[:new].to_s, index: index }
+    end
+
+    # Exact match first; on a miss, a whitespace-tolerant line match. Either
+    # level must resolve to exactly one region. A total miss reports the
+    # closest region and its precise difference, so the model's retry can be
+    # one-shot.
+    def locate(content, edit)
+      exact_match(content, edit) || fuzzy_match(content, edit) ||
+        raise(EditError, not_found_message(content, edit))
+    end
+
+    def replace_every(content, old, new)
+      count = content.enum_for(:scan, old).count
+      raise EditError, not_found_message(content, { old: old, index: 0 }) if count.zero?
+
+      # Block form keeps both sides literal; a bare string replacement would
+      # interpret backslash sequences.
+      Result.new(content: content.gsub(old) { new }, count: count)
+    end
+
+    # Match the document's dominant newline style so a replacement authored
+    # with bare LF does not mix endings into a CRLF document.
+    def adapt_newlines(content, text)
+      crlf = content.scan("\r\n").length
+      bare = content.scan(/(?<!\r)\n/).length
+      return text.gsub(/\r?\n/, "\r\n") if crlf > bare
+
+      crlf.positive? || bare.positive? ? text.gsub("\r\n", "\n") : text
+    end
+
+    def exact_match(content, edit)
+      offsets = occurrence_offsets(content, edit[:old])
+      return nil if offsets.empty?
+
+      if offsets.length > 1
+        lines = offsets.map { |offset| line_number_at(content, offset) }
+        raise EditError, ambiguous_message(edit, lines)
+      end
+      first = offsets.first
+      Match.new(first, first + edit[:old].length, edit[:new], edit[:index])
+    end
+
+    def occurrence_offsets(content, needle)
+      offsets = []
+      offset = content.index(needle)
+      while offset
+        offsets << offset
+        offset = content.index(needle, offset + 1)
+      end
+      offsets
+    end
+
+    def line_number_at(content, offset) = content[0...offset].count("\n") + 1
+
+    def ambiguous_message(edit, line_numbers)
+      shown = line_numbers.first(4).join(", ")
+      shown += ", ..." if line_numbers.length > 4
+      "edits[#{edit[:index]}] old text matched #{line_numbers.length} places " \
+        "(lines #{shown}). Add surrounding lines until it is unique, or set " \
+        "replace_all: true to change all #{line_numbers.length}."
+    end
+
+    # Match the old text's lines against a window of content lines, comparing
+    # each line stripped of leading and trailing whitespace. The matched region
+    # is the exact original bytes those content lines span.
+    def fuzzy_match(content, edit)
+      lines = line_spans(content)
+      wanted = edit[:old].lines.map(&:strip)
+      wanted.pop if wanted.last == "" # a trailing newline in old text is not a line to match
+      return nil if wanted.empty?
+
+      windows = matching_windows(lines, wanted)
+      return nil if windows.empty?
+
+      raise EditError, ambiguous_message(edit, windows.map { |w| w + 1 }) if windows.length > 1
+
+      first = windows.first
+      Match.new(lines[first][:start], lines[first + wanted.length - 1][:finish],
+                edit[:new], edit[:index])
+    end
+
+    # When nothing matched, show the model the closest region and exactly how
+    # it differs, so the retry is one shot instead of a guessing loop.
+    def not_found_message(content, edit)
+      base = "edits[#{edit[:index]}] old text was not found"
+      near = nearest_region(content, edit[:old])
+      unless near
+        return "#{base}. Copy old_string verbatim from read_file output, " \
+               "without line-number prefixes."
+      end
+
+      "#{base}. Closest region is lines #{near[:from]}-#{near[:to]}; it differs at " \
+        "line #{near[:line]}: your text #{near[:yours].inspect} vs the document's " \
+        "#{near[:theirs].inspect}#{near[:hint]}. Copy old_string verbatim from " \
+        "read_file output, then resend."
+    end
+
+    # The window with the most stripped-equal lines, plus its first differing
+    # line pair.
+    def nearest_region(content, old_text)
+      lines = line_spans(content)
+      wanted_raw = old_text.lines.map(&:chomp)
+      wanted = wanted_raw.map(&:strip)
+      wanted.pop && wanted_raw.pop if wanted.last == ""
+      return nil if wanted.empty? || lines.length < wanted.length
+
+      best = best_window(lines, wanted)
+      return nil unless best
+
+      diff_at = (0...wanted.length).find { |j| lines[best + j][:stripped] != wanted[j] }
+      return nil unless diff_at
+
+      yours = wanted_raw[diff_at]
+      theirs = content.lines[best + diff_at].to_s.chomp
+      hint = yours.strip == theirs.strip ? " (differs only in whitespace)" : ""
+      { from: best + 1, to: best + wanted.length, line: best + diff_at + 1,
+        yours: yours, theirs: theirs, hint: hint }
+    end
+
+    # Score windows by per-line bigram similarity, so a one-character typo in
+    # a one-line old_string still finds its region. Only a window at least
+    # half-similar overall is worth reporting.
+    def best_window(lines, wanted)
+      best = nil
+      best_score = wanted.length / 2.0
+      (0..(lines.length - wanted.length)).each do |i|
+        score = (0...wanted.length).sum { |j| similarity(lines[i + j][:stripped], wanted[j]) }
+        if score > best_score
+          best_score = score
+          best = i
+        end
+      end
+      best
+    end
+
+    def similarity(left, right)
+      return 1.0 if left == right
+      return 0.0 if left.empty? || right.empty?
+
+      pairs_left = bigrams(left)
+      pairs_right = bigrams(right)
+      return 0.0 if pairs_left.empty? || pairs_right.empty?
+
+      (2.0 * (pairs_left & pairs_right).length) / (pairs_left.length + pairs_right.length)
+    end
+
+    def bigrams(text) = (0...(text.length - 1)).map { |i| text[i, 2] }.uniq
+
+    def matching_windows(lines, wanted)
+      (0..(lines.length - wanted.length)).select do |i|
+        wanted.each_with_index.all? { |line, j| lines[i + j][:stripped] == line }
+      end
+    end
+
+    # Each line with its character span in the original and its stripped form.
+    # A leading BOM is invisible to matching, and the first span starts after
+    # it, so a replacement at the top of the document never swallows it.
+    def line_spans(content)
+      offset = 0
+      content.lines.map do |line|
+        bom = offset.zero? && line.start_with?("\uFEFF") ? 1 : 0
+        span = { start: offset + bom, finish: offset + line.length,
+                 stripped: line.delete_prefix("\uFEFF").strip }
+        offset += line.length
+        span
+      end
+    end
+
+    def reject_overlaps(matches)
+      matches.each_cons(2) do |a, b|
+        next if a.finish <= b.start
+
+        raise EditError, "edits[#{a.edit_index}] and edits[#{b.edit_index}] overlap; " \
+                         "merge them or target separate regions"
+      end
+    end
+  end
+end

data/lib/mistri/errors.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Mistri
+  # Root of every error Mistri raises, so a host can rescue Mistri::Error.
+  #
+  # Only failures the model cannot recover from raise: configuration, transport,
+  # budgets, aborts. A tool that fails during a run becomes an in-band tool
+  # result the model can react to, never an exception out of the loop.
+  class Error < StandardError; end
+
+  # Missing or contradictory setup: an unknown model, an absent API key.
+  class ConfigurationError < Error; end
+
+  # A provider request failed. Carries the HTTP status and response body when
+  # the transport got that far.
+  class ProviderError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message || self.class.default_message)
+    end
+
+    # The full story for logs and error turns: the response names the fix far
+    # more often than the status line does.
+    def describe
+      parts = [message]
+      parts << "status #{status}" if status
+      parts << body.to_s[0, 300] if body && !body.to_s.strip.empty?
+      parts.join(" | ")
+    end
+
+    def self.default_message = "provider request failed"
+  end
+
+  class AuthenticationError < ProviderError
+    def self.default_message = "invalid or missing API key"
+  end
+
+  class RateLimitError < ProviderError
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **)
+      @retry_after = retry_after
+      super(message, **)
+    end
+
+    def self.default_message = "rate limited"
+  end
+
+  class OverloadedError < ProviderError
+    def self.default_message = "provider overloaded"
+  end
+
+  class ServerError < ProviderError
+    def self.default_message = "provider server error"
+  end
+
+  # Tool arguments or structured output that violate their declared schema.
+  class SchemaError < Error; end
+
+  # A run cancelled by the host, raised only when the caller opts into raising.
+  class AbortError < Error; end
+
+  # A run stopped by its turn, token, cost, or wall-clock budget.
+  class BudgetError < Error; end
+
+  # A text edit that did not match uniquely, or overlapped another edit.
+  class EditError < Error; end
+
+  # Compaction could not produce a usable summary.
+  class CompactionError < Error; end
+
+  # The machine-readable shape of a stream failure, carried on errored
+  # assistant messages so retry policies and hosts can classify without
+  # parsing prose. Strings are the assemblers' synthesized truncation
+  # reasons.
+  module ErrorData
+    module_function
+
+    def for(reason)
+      case reason
+      when RateLimitError
+        { "type" => "RateLimitError", "status" => reason.status,
+          "retry_after" => reason.retry_after }.compact
+      when ProviderError
+        { "type" => reason.class.name.split("::").last, "status" => reason.status }.compact
+      when Exception then { "type" => reason.class.name }
+      else { "type" => "TruncatedStream" }
+      end
+    end
+  end
+end

data/lib/mistri/event.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Mistri
+  # One event in a streamed assistant turn. A stream is one :start, then a
+  # start/delta/end trio per content block (text, thinking, or toolcall), then
+  # exactly one terminal event: :done on success or :error on failure, carrying
+  # the complete message and its stop reason.
+  #
+  # `partial` is an immutable snapshot of the assistant message so far, safe to
+  # hold across events. `content_index` is the block's position in that
+  # message's content list.
+  # origin names the sub-agent an event came from: nil for this agent's own
+  # turns, and nesting joins names left to right ("researcher>writer").
+  class Event < Data.define(:type, :content_index, :delta, :content, :tool_call,
+                            :reason, :message, :error_message, :partial, :origin)
+    # The stream types come from a provider mid-turn; the loop adds
+    # :tool_result after it runs each tool, :approval_needed when a gated
+    # call parks for a human, and :compacting/:compaction around a context
+    # compaction, so one subscription sees the whole exchange.
+    TYPES = %i[
+      start
+      text_start text_delta text_end
+      thinking_start thinking_delta thinking_end
+      toolcall_start toolcall_delta toolcall_end
+      done error
+      tool_result approval_needed
+      compacting compaction
+      retry
+    ].freeze
+
+    def initialize(type:, content_index: nil, delta: nil, content: nil, tool_call: nil,
+                   reason: nil, message: nil, error_message: nil, partial: nil, origin: nil)
+      raise ArgumentError, "unknown event type #{type.inspect}" unless TYPES.include?(type)
+
+      super
+    end
+
+    def done? = type == :done
+
+    def error? = type == :error
+
+    def terminal? = done? || error?
+
+    # Partials are ephemeral streaming state and stay out of serialization.
+    def to_h
+      { type:, content_index:, delta:, content:, tool_call: tool_call&.to_h,
+        reason:, message: message&.to_h, error_message:, origin: }.compact
+    end
+  end
+end

data/lib/mistri/memory.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mistri
+  # Durable knowledge that outlives a session, living wherever the host says:
+  # an org's row, a user record, a file. What memory means (per org, per
+  # user, per project) is the host's call; Mistri only reads and replaces it.
+  #
+  #   memory = Mistri::Memory.new(
+  #     read: -> { org.agent_memory.to_s },
+  #     write: ->(text) { org.update!(agent_memory: text) }
+  #   )
+  #   agent = Mistri.agent("claude-opus-4-8", tools: [*Mistri::Tools.memory(memory)])
+  class Memory
+    def initialize(read:, write:)
+      @read = read
+      @write = write
+    end
+
+    def read = @read.call.to_s
+
+    def replace(content)
+      @write.call(content.to_s)
+      nil
+    end
+  end
+end

data/lib/mistri/message.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Mistri
+  # One message in a conversation, the single shape every provider translates to
+  # and from its wire format. Immutable: streaming builds snapshots, sessions
+  # replay values, and nothing aliases across threads.
+  #
+  # Roles: :system, :user, :assistant, :tool (a tool result linked back by
+  # tool_call_id). Assistant messages carry the model and provider that produced
+  # them, which is what lets a later turn replay history across models, plus
+  # usage and the stop reason.
+  #
+  # ui is a tool result's host-only channel: it persists with the message and
+  # rides its :tool_result event, but no serializer ever sends it to a model.
+  # error is the machine-readable failure on an errored turn (ErrorData
+  # shape); error_message stays the human story.
+  class Message < Data.define(:role, :content, :tool_call_id, :tool_name,
+                              :model, :provider, :usage, :stop_reason, :error_message, :ui,
+                              :error)
+    ROLES = %i[system user assistant tool].freeze
+
+    def initialize(role:, content: nil, tool_call_id: nil, tool_name: nil, model: nil,
+                   provider: nil, usage: nil, stop_reason: nil, error_message: nil, ui: nil,
+                   error: nil)
+      role = role.to_sym
+      raise ArgumentError, "unknown role #{role.inspect}" unless ROLES.include?(role)
+      if stop_reason && !StopReason.valid?(stop_reason)
+        raise ArgumentError, "unknown stop reason #{stop_reason.inspect}"
+      end
+
+      super(role:, content: Content.wrap(content).freeze, tool_call_id:, tool_name:,
+            model:, provider:, usage:, stop_reason:, error_message:, ui:, error:)
+    end
+
+    def self.system(content) = new(role: :system, content:)
+
+    def self.user(content) = new(role: :user, content:)
+
+    # A user turn carrying images alongside optional text.
+    def self.user_with_images(content, images = [])
+      images = Array(images)
+      return user(content) if images.empty?
+
+      text = content.to_s
+      blocks = text.empty? ? images : [Content::Text.new(text:), *images]
+      new(role: :user, content: blocks)
+    end
+
+    def self.assistant(content: nil, tool_calls: [], **meta)
+      new(role: :assistant, content: [*Content.wrap(content), *tool_calls], **meta)
+    end
+
+    def self.tool(content:, tool_call_id:, tool_name: nil, ui: nil)
+      new(role: :tool, content:, tool_call_id:, tool_name:, ui:)
+    end
+
+    def self.from_h(hash)
+      h = hash.transform_keys(&:to_s)
+      new(role: h.fetch("role").to_sym,
+          content: Array(h["content"]).map { |block| Content.from_h(block) },
+          tool_call_id: h["tool_call_id"], tool_name: h["tool_name"],
+          model: h["model"], provider: h["provider"]&.to_sym,
+          usage: h["usage"] && Usage.from_h(h["usage"]),
+          stop_reason: h["stop_reason"]&.to_sym, error_message: h["error_message"],
+          ui: h["ui"], error: h["error"])
+    end
+
+    def system? = role == :system
+    def user? = role == :user
+    def assistant? = role == :assistant
+    def tool? = role == :tool
+
+    # Every Text block joined, or nil when the turn carried no text.
+    def text
+      texts = content.grep(Content::Text)
+      texts.empty? ? nil : texts.map(&:text).join
+    end
+
+    def tool_calls = content.grep(ToolCall)
+
+    def tool_calls? = content.any?(ToolCall)
+
+    # A serialization shape, not the member hash: rebuild with .from_h,
+    # never with new(**to_h).
+    def to_h
+      { role:, content: content.map(&:to_h), tool_call_id:, tool_name:, model:,
+        provider:, usage: usage&.to_h, stop_reason:, error_message:, ui:, error: }.compact
+    end
+  end
+end

data/lib/mistri/models.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Mistri
+  # The model catalog: capability data for known models, with graceful
+  # passthrough for unknown ones. An id missing here still works everywhere;
+  # the catalog only improves defaults (output ceilings, provider inference),
+  # so a brand-new model is usable the day it ships.
+  module Models
+    # thinking is how the model accepts a reasoning request: :adaptive (the
+    # model decides), :budget (a token budget), or :effort. It is what keeps
+    # a provider from sending an unsupported thinking shape that 400s.
+    Model = Data.define(:id, :provider, :max_output, :context_window, :thinking)
+
+    CATALOG = [
+      ["claude-fable-5", :anthropic, 128_000, 200_000, :adaptive],
+      ["claude-opus-4-8", :anthropic, 128_000, 200_000, :adaptive],
+      ["claude-opus-4-7", :anthropic, 128_000, 200_000, :adaptive],
+      ["claude-opus-4-6", :anthropic, 128_000, 200_000, :adaptive],
+      ["claude-sonnet-5", :anthropic, 128_000, 200_000, :adaptive],
+      ["claude-sonnet-4-6", :anthropic, 128_000, 200_000, :adaptive],
+      ["claude-haiku-4-5", :anthropic, 64_000, 200_000, :budget],
+      ["gpt-5.5", :openai, 128_000, 400_000, :effort],
+      ["gpt-5.4", :openai, 128_000, 400_000, :effort],
+      ["gpt-5-nano", :openai, 128_000, 400_000, :effort],
+      ["gemini-3.5-flash", :gemini, 65_536, 1_048_576, :level],
+      ["gemini-3.1-pro-preview", :gemini, 65_536, 1_048_576, :level],
+      ["gemini-2.5-pro", :gemini, 65_536, 1_048_576, :budget],
+      ["gemini-2.5-flash", :gemini, 65_536, 1_048_576, :budget]
+    ].to_h do |id, provider, max_output, context_window, thinking|
+      [id, Model.new(id:, provider:, max_output:, context_window:, thinking:)]
+    end.freeze
+
+    # Dated aliases resolve to their base entry: claude-opus-4-8-20260115 and
+    # gpt-5.4-2025-04-14 both match their base ids.
+    def self.find(id)
+      CATALOG[id] || CATALOG[id.to_s.sub(/-\d{8}\z/, "").sub(/-\d{4}-\d{2}-\d{2}\z/, "")]
+    end
+
+    def self.max_output(id) = find(id)&.max_output
+
+    def self.thinking(id) = find(id)&.thinking
+  end
+end