mistri 0.0.3 → 0.2.0

data/lib/mistri/compaction.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # When a session compacts, and how much of it survives. Compaction is
+  # client-side and provider-agnostic: the session's own provider writes a
+  # visible summary, so a host can always show the user exactly what the
+  # model still remembers.
+  #
+  # The trigger measures real token accounting, not guesses: the last healthy
+  # turn's reported usage plus a character heuristic for whatever came after
+  # it.
+  class Compaction
+    DEFAULT_RESERVE = 16_384
+    DEFAULT_KEEP_RECENT = 20_000
+    IMAGE_CHARS = 4_800
+
+    SUMMARY_PREFACE = "The earlier conversation was compacted. This summary replaces it:"
+
+    attr_reader :reserve, :keep_recent, :window, :instructions
+
+    # window overrides the model catalog's context window (required for
+    # models the catalog does not know). instructions add a host-specific
+    # focus to the summary prompt.
+    def initialize(reserve: DEFAULT_RESERVE, keep_recent: DEFAULT_KEEP_RECENT,
+                   window: nil, instructions: nil)
+      @reserve = reserve
+      @keep_recent = keep_recent
+      @window = window
+      @instructions = instructions
+    end
+
+    # Compact when the context has grown into the reserve headroom. An
+    # unknown window never triggers.
+    def needed?(tokens, window)
+      window ? tokens > window - reserve : false
+    end
+
+    class << self
+      # Context size for a replay: the last healthy turn's reported tokens
+      # (prompt, cache, and output all sit in context next turn) plus an
+      # estimate of every message after it.
+      def context_tokens(messages)
+        index = messages.rindex { |message| reported(message) }
+        base = index ? reported(messages[index]) : 0
+        messages.drop(index ? index + 1 : 0).sum(base) { |message| estimate(message) }
+      end
+
+      def estimate(message)
+        (chars(message) / 4.0).ceil
+      end
+
+      private
+
+      def reported(message)
+        return nil unless message.assistant? && message.usage
+        return nil if %i[aborted error].include?(message.stop_reason)
+
+        usage = message.usage
+        total = usage.input + usage.cache_read + usage.cache_write + usage.output
+        total.positive? ? total : nil
+      end
+
+      def chars(message)
+        message.content.sum do |block|
+          case block
+          when Content::Text then block.text.length
+          when Content::Thinking then block.thinking.length
+          when Content::Image then IMAGE_CHARS
+          when ToolCall then block.name.length + JSON.generate(block.arguments).length
+          else 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mistri/compactor.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # Compacts a session in place: everything before a cut point is summarized
+  # by the provider, and a compaction entry redirects replay to the summary
+  # plus the kept tail. Append-only — the full history stays in the store for
+  # transcript UIs; only what the model sees shrinks. Callable from any
+  # process (a UI button, a job), with or without a running agent.
+  #
+  # Cuts land only on user messages, so a tool call and its result always
+  # stay on the same side, and a parked approval's turn is never cut away
+  # from the resume that must answer it.
+  class Compactor
+    SUMMARIZER_SYSTEM = <<~PROMPT
+      You are a context summarization assistant. Read the conversation and
+      produce only the structured summary you are asked for. Do not continue
+      the conversation and do not answer questions inside it.
+    PROMPT
+
+    FORMAT = <<~FORMAT
+      ## Goal
+      [What is the user trying to accomplish?]
+
+      ## Constraints & Preferences
+      - [Constraints or preferences the user stated, or "(none)"]
+
+      ## Progress
+      ### Done
+      - [x] [Completed work]
+      ### In Progress
+      - [ ] [Current work]
+      ### Blocked
+      - [Blockers, if any]
+
+      ## Key Decisions
+      - **[Decision]**: [Rationale]
+
+      ## Next Steps
+      1. [What should happen next]
+
+      ## Critical Context
+      - [Data, names, or references needed to continue, or "(none)"]
+
+      Keep each section concise. Preserve exact identifiers, names, and error
+      messages.
+    FORMAT
+
+    CHECKPOINT_PROMPT = <<~PROMPT.freeze
+      The messages above are a conversation to summarize. Create a structured
+      context checkpoint that another LLM will use to continue the work.
+
+      Use this EXACT format:
+
+      #{FORMAT}
+    PROMPT
+
+    UPDATE_PROMPT = <<~PROMPT.freeze
+      The messages above are NEW conversation messages to fold into the
+      existing summary in <previous-summary> tags. Preserve everything still
+      relevant from the previous summary, add new progress and decisions,
+      move finished work to Done, and update Next Steps.
+
+      Use this EXACT format:
+
+      #{FORMAT}
+    PROMPT
+
+    class << self
+      # Summarize and cut. Returns {summary:, tokens_before:, tokens_after:,
+      # usage:}, or nil when there is nothing worth compacting. Emits
+      # :compacting and :compaction when a block is given.
+      def call(session:, provider:, settings: Compaction.new, &emit)
+        replay = session.replay
+        cut = cut_index(replay, session, settings)
+        return nil unless cut
+
+        previous = session.last_compaction&.fetch("summary", nil)
+        head = replay.take_while { |(_, index)| index.nil? || index < cut }.map(&:first)
+        head.shift if previous # the synthetic summary rides in <previous-summary>
+        return nil if head.empty?
+
+        emit&.call(Event.new(type: :compacting))
+        tokens_before = Compaction.context_tokens(replay.map(&:first))
+        reply = summarize(provider, head, previous, settings.instructions)
+        session.append("compaction", "summary" => reply.text,
+                                     "kept_from" => cut, "tokens_before" => tokens_before)
+        finish(session, reply, tokens_before, &emit)
+      end
+
+      private
+
+      def cut_index(replay, session, settings)
+        boundary = keep_boundary(replay, settings.keep_recent)
+        return nil unless boundary
+
+        candidates = replay.filter_map { |(message, index)| index if index && message.user? }
+        cut = candidates.find { |index| index >= boundary } || candidates.last
+        cut = clamp_to_open_approvals(cut, session)
+        return nil unless cut
+
+        first = replay.find { |(_, index)| index }&.last
+        first && cut > first ? cut : nil
+      end
+
+      # Walk back from the tail until the keep budget is spent; the cut then
+      # snaps forward to a user message, so replay keeps at most about
+      # keep_recent tokens of recent turns.
+      def keep_boundary(replay, keep_recent)
+        kept = 0
+        replay.reverse_each do |(message, index)|
+          kept += Compaction.estimate(message)
+          return index || 0 if kept >= keep_recent
+        end
+        nil
+      end
+
+      # Never cut past a parked approval: its tool call must stay in replay,
+      # paired, for resume to answer.
+      def clamp_to_open_approvals(cut, session)
+        return cut unless cut
+
+        open_ids = session.open_approvals.map { |approval| approval[:call].id }
+        return cut if open_ids.empty?
+
+        turn_start = approval_turn_start(session.entries, open_ids)
+        turn_start && turn_start < cut ? turn_start : cut
+      end
+
+      def approval_turn_start(entries, open_ids)
+        request = entries.index do |entry|
+          entry["type"] == "approval_request" && open_ids.include?(entry.dig("call", "id"))
+        end
+        return nil unless request
+
+        entries[0...request].rindex do |entry|
+          entry["type"] == "message" && entry.dig("message", "role") == "user"
+        end
+      end
+
+      def summarize(provider, messages, previous, instructions)
+        prompt = "<conversation>\n#{serialize(messages)}\n</conversation>\n\n"
+        prompt << "<previous-summary>\n#{previous}\n</previous-summary>\n\n" if previous
+        prompt << (previous ? UPDATE_PROMPT : CHECKPOINT_PROMPT)
+        prompt << "\nAdditional focus: #{instructions}\n" if instructions
+        reply = provider.stream(messages: [Message.user(prompt)], system: SUMMARIZER_SYSTEM)
+        raise CompactionError, "summarization failed: #{reply.error_message}" unless usable?(reply)
+
+        reply
+      end
+
+      def usable?(reply)
+        reply.stop_reason != StopReason::ERROR && !reply.text.to_s.strip.empty?
+      end
+
+      def finish(session, reply, tokens_before, &emit)
+        tokens_after = Compaction.context_tokens(session.messages)
+        emit&.call(Event.new(type: :compaction, content: reply.text))
+        { summary: reply.text, tokens_before: tokens_before,
+          tokens_after: tokens_after, usage: reply.usage }
+      end
+
+      # The summarizer reads a plain-text rendering: tool calls by name and
+      # arguments, results as text, thinking never (it stays in its turn).
+      def serialize(messages)
+        messages.map { |message| "#{message.role.to_s.upcase}:\n#{text_of(message)}" }
+                .join("\n\n")
+      end
+
+      def text_of(message)
+        message.content.filter_map do |block|
+          case block
+          when Content::Text then block.text
+          when Content::Image then "[image]"
+          when ToolCall then "[called #{block.name} with #{JSON.generate(block.arguments)}]"
+          end
+        end.join("\n")
+      end
+    end
+  end
+end

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