mistri 0.0.3 → 0.2.0

data/lib/mistri/mcp.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # Bridge Model Context Protocol servers into Mistri tools: list a server's
+  # tools, hand them to an agent, and everything the harness already does
+  # composes — approval gates on third-party write tools, retries, sub-agent
+  # pools, the ui channel.
+  #
+  #   client = Mistri::MCP::Client.new(url: "https://mcp.linear.app/mcp",
+  #                                    token: -> { connection.fresh_token })
+  #   agent = Mistri.agent("claude-opus-4-8",
+  #                        tools: Mistri::MCP.tools(client, prefix: "linear"))
+  #
+  # The bridge is duck-typed: any client responding to tools (an array of
+  # {"name", "description", "inputSchema"} hashes) and call_tool(name, args)
+  # bridges the same way, so the official mcp gem's client plugs in too.
+  module MCP
+    # A protocol-level failure: a JSON-RPC error, a missing response, an
+    # unsupported negotiation.
+    class Error < Mistri::Error
+      attr_reader :code
+
+      def initialize(message = nil, code: nil)
+        @code = code
+        super(message)
+      end
+    end
+
+    # The server expired this client's session (a 404 with a session
+    # attached); the spec says start a fresh one, and Client does.
+    class SessionExpired < Error; end
+
+    module_function
+
+    # The server's tools as Mistri tools. allow/deny filter by remote name,
+    # prefix namespaces local names ("linear__create_issue") against
+    # collisions, and gates marks tools needing human approval
+    # (gates: { "create_issue" => true }, or needs_approval: for all).
+    def tools(client, allow: nil, deny: [], prefix: nil, needs_approval: false, gates: {})
+      listed = client.tools
+      listed = listed.select { |tool| allow.include?(tool["name"]) } if allow
+      listed = listed.reject { |tool| deny.include?(tool["name"]) }
+      listed.map do |tool|
+        bridge(client, tool, prefix: prefix, gate: gates.fetch(tool["name"], needs_approval))
+      end
+    end
+
+    def bridge(client, spec, prefix: nil, gate: false)
+      remote = spec.fetch("name")
+      local = prefix ? "#{prefix}__#{remote}" : remote
+      Tool.define(local, spec["description"].to_s,
+                  input_schema: spec["inputSchema"] || Tool::EMPTY_SCHEMA,
+                  needs_approval: gate) do |args|
+        answer(client.call_tool(remote, args || {}))
+      end
+    end
+
+    # An MCP result becomes model-readable content: text joins, images ride
+    # as image blocks, and isError answers in band so the model can react.
+    def answer(result)
+      blocks = Array(result["content"]).map { |block| convert(block) }
+      if result["isError"]
+        text = blocks.grep(String).join("\n")
+        return "MCP tool error: #{text.empty? ? "unknown error" : text}"
+      end
+      if blocks.empty? && result["structuredContent"]
+        return JSON.generate(result["structuredContent"])
+      end
+      return blocks.join("\n") if blocks.all?(String)
+
+      blocks
+    end
+
+    def convert(block)
+      case block["type"]
+      when "text" then block["text"].to_s
+      when "image"
+        Content::Image.from_bytes(block["data"].to_s.unpack1("m"),
+                                  mime_type: block["mimeType"] || "image/png")
+      when "resource" then resource_text(block["resource"] || {})
+      when "resource_link" then "[resource: #{block["uri"]}]"
+      else "[unsupported #{block["type"]} content]"
+      end
+    end
+
+    def resource_text(resource)
+      resource["text"] || "[resource: #{resource["uri"]}]"
+    end
+  end
+end
+
+require_relative "mcp/wires"
+require_relative "mcp/client"
+require_relative "mcp/oauth"

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

data/lib/mistri/partial_json.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # Parses the JSON prefix a model has emitted so far, so in-flight tool-call
+  # arguments are readable before the closing brace arrives. Best effort by
+  # contract: never raises, drops a dangling key or half-written token, and
+  # returns {} for hopeless input.
+  module PartialJson
+    def self.parse(text)
+      s = text.to_s.strip
+      return {} if s.empty?
+
+      value = Parser.new(s).parse
+      value.equal?(Parser::NOTHING) ? {} : value
+    rescue StandardError, SystemStackError
+      {}
+    end
+
+    # Recursive descent over the prefix. Truncation trips @partial, and every
+    # frame unwinds keeping the structure built so far.
+    class Parser
+      NOTHING = Object.new
+      LITERALS = { "true" => true, "false" => false, "null" => nil }.freeze
+
+      # Nesting past this is treated as truncated: a model's real tool
+      # arguments never nest this deep, and the cap keeps a pathological input
+      # from overflowing the stack.
+      MAX_DEPTH = 256
+
+      def initialize(source)
+        @s = source
+        @n = source.length
+        @i = 0
+        @partial = false
+        @depth = 0
+      end
+
+      def parse = value
+
+      private
+
+      def value
+        skip_ws
+        return truncated if eof?
+
+        case @s[@i]
+        when '"' then string
+        when "{" then nested { object }
+        when "[" then nested { array }
+        else scalar
+        end
+      end
+
+      def nested
+        return truncated if @depth >= MAX_DEPTH
+
+        @depth += 1
+        begin
+          yield
+        ensure
+          @depth -= 1
+        end
+      end
+
+      def object
+        @i += 1
+        obj = {}
+        until @partial
+          skip_ws
+          break truncated if eof?
+          break @i += 1 if @s[@i] == "}"
+          break unless @s[@i] == '"'
+
+          key, val = pair
+          obj[key] = val unless key.equal?(NOTHING) || val.equal?(NOTHING)
+          skip_ws
+          @i += 1 if !eof? && @s[@i] == ","
+        end
+        obj
+      end
+
+      # One key/value. A truncation before the value completes the key's
+      # last-known state: mid-key or mid-separator drops the pair entirely.
+      def pair
+        key = string
+        return [NOTHING, NOTHING] if @partial
+
+        skip_ws
+        return [NOTHING, truncated] if eof?
+        return [NOTHING, NOTHING] unless @s[@i] == ":"
+
+        @i += 1
+        [key, value]
+      end
+
+      def array
+        @i += 1
+        arr = []
+        until @partial
+          skip_ws
+          break truncated if eof?
+          break @i += 1 if @s[@i] == "]"
+
+          element = value
+          arr << element unless element.equal?(NOTHING)
+          skip_ws
+          @i += 1 if !eof? && @s[@i] == ","
+        end
+        arr
+      end
+
+      def string
+        start = @i
+        @i += 1
+        escaped = false
+        while @i < @n
+          case
+          when escaped then escaped = false
+          when @s[@i] == "\\" then escaped = true
+          when @s[@i] == '"'
+            @i += 1
+            return decode(@s[start...@i])
+          end
+          @i += 1
+        end
+        truncated
+        salvage_string(@s[start..])
+      end
+
+      # Close an unterminated string, first shedding a half-written escape: a
+      # partial \uXXXX, or a lone trailing backslash. A backslash is only
+      # dangling when the trailing run of them is odd; an even run is complete
+      # escaped backslashes and must be kept.
+      def salvage_string(fragment)
+        candidate = fragment.sub(/\\u[0-9a-fA-F]{0,3}\z/, "")
+        trailing = candidate[/\\+\z/]
+        candidate = candidate[0..-2] if trailing&.length&.odd?
+        decode(%(#{candidate}"))
+      end
+
+      def scalar
+        start = @i
+        @i += 1 while @i < @n && !"},] \n\r\t".include?(@s[@i])
+        token = @s[start...@i]
+        # A structural character in value position: consume it so the caller's
+        # loop always makes progress.
+        return (@i += 1) && NOTHING if token.empty?
+
+        truncated if eof?
+        literal(token) { number(token) }
+      end
+
+      def literal(token)
+        return LITERALS[token] if LITERALS.key?(token)
+
+        if @partial
+          match = LITERALS.keys.find { |word| word.start_with?(token) }
+          return LITERALS[match] if match
+        end
+        yield
+      end
+
+      def number(token)
+        Integer(token)
+      rescue ArgumentError
+        begin
+          finite(Float(token))
+        rescue ArgumentError
+          trimmed_number(token)
+        end
+      end
+
+      # A number cut mid-token: shed the dangling exponent, decimal point, or
+      # bare minus and retry.
+      def trimmed_number(token)
+        trimmed = token.sub(/[eE][+-]?\z/, "").sub(/\.\z/, "")
+        return NOTHING if trimmed.empty? || trimmed == "-"
+
+        finite(Float(trimmed))
+      rescue ArgumentError
+        NOTHING
+      end
+
+      # A model that emits 1e999 yields Float::INFINITY, which JSON cannot
+      # generate, so it would crash replay and persistence. Drop it.
+      def finite(number)
+        number.finite? ? number : NOTHING
+      end
+
+      def decode(json_string)
+        JSON.parse(json_string)
+      rescue JSON::ParserError
+        NOTHING
+      end
+
+      def skip_ws
+        @i += 1 while @i < @n && " \n\r\t".include?(@s[@i])
+      end
+
+      def eof? = @i >= @n
+
+      def truncated
+        @partial = true
+        NOTHING
+      end
+    end
+  end
+end

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

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Providers
+    class Anthropic
+      # Folds the Messages API stream into the event union, building the
+      # assistant message block by block. Every emitted event carries an
+      # immutable snapshot of the message so far; in-flight tool arguments
+      # parse via PartialJson so consumers can read them mid-stream.
+      #
+      # Unknown event and block types are skipped by contract: the API adds
+      # types over time and a live stream must survive them.
+      class Assembler
+        def initialize(model:)
+          @model = model
+          @blocks = []
+          @current = nil
+          @usage = Usage.zero
+          @stop_reason = nil
+          @done = false
+        end
+
+        def feed(record, &)
+          case record["type"]
+          when "message_start" then @usage = parse_usage(record.dig("message", "usage"))
+          when "content_block_start" then start_block(record, &)
+          when "content_block_delta" then delta_block(record, &)
+          when "content_block_stop" then stop_block(record, &)
+          when "message_delta" then message_delta(record)
+          when "message_stop" then @done = true
+          when "error" then @error = wire_error(record["error"])
+          end
+        end
+
+        # Close the stream: the terminal event reflects how it ended. A stream
+        # that ended without message_stop was truncated (a dropped proxy, say),
+        # not user-aborted, so it fails for the loop to retry rather than
+        # reading as a cancellation.
+        def finish(&emit)
+          return fail_stream(@error, &emit) if @error
+          return fail_stream("stream ended without message_stop", &emit) unless @done
+
+          @message = assemble(stop_reason: @stop_reason || StopReason::STOP)
+          emit&.call(Event.new(type: :done, reason: @message.stop_reason, message: @message))
+          @message
+        end
+
+        def abort(&emit)
+          finalize_current
+          @message = assemble(stop_reason: StopReason::ABORTED, error_message: "aborted")
+          emit&.call(Event.new(type: :error, reason: StopReason::ABORTED, message: @message,
+                               error_message: "aborted"))
+          @message
+        end
+
+        # In-stream failures carry a wire type; overloaded ones must classify
+        # as retryable, not fold into prose.
+        def wire_error(payload)
+          message = payload&.dig("message") || "provider error"
+          klass = payload&.dig("type").to_s.include?("overloaded") ? OverloadedError : ProviderError
+          klass.new(message)
+        end
+
+        def fail_stream(reason, &emit)
+          finalize_current
+          text = case reason
+                 when ProviderError then "#{reason.class}: #{reason.describe}"
+                 when Exception then "#{reason.class}: #{reason.message}"
+                 else reason.to_s
+                 end
+          @message = assemble(stop_reason: StopReason::ERROR, error_message: text,
+                              error: ErrorData.for(reason))
+          emit&.call(Event.new(type: :error, reason: StopReason::ERROR, message: @message,
+                               error_message: text))
+          @message
+        end
+
+        def message = @message ||= finish
+
+        Builder = Struct.new(:kind, :index, :text, :json, :signature, :id, :name, :redacted)
+
+        private
+
+        def start_block(record, &)
+          block = record["content_block"] || {}
+          kind = { "text" => :text, "thinking" => :thinking, "redacted_thinking" => :thinking,
+                   "tool_use" => :toolcall }[block["type"]]
+          return unless kind
+
+          @current = Builder.new(kind, @blocks.size, +"", +"", nil,
+                                 block["id"], block["name"], block["type"] == "redacted_thinking")
+          @current.signature = block["data"] if @current.redacted
+          emit_event(:"#{kind}_start", content_index: @current.index, &)
+        end
+
+        def delta_block(record, &)
+          return unless @current
+
+          delta = record["delta"] || {}
+          case delta["type"]
+          when "text_delta" then text_delta(delta["text"], &)
+          when "thinking_delta" then thinking_delta(delta["thinking"], &)
+          when "signature_delta"
+            @current.signature = "#{@current.signature}#{delta["signature"]}"
+          when "input_json_delta" then input_delta(delta["partial_json"], &)
+          end
+        end
+
+        def text_delta(text, &)
+          @current.text << text.to_s
+          emit_event(:text_delta, content_index: @current.index, delta: text, &)
+        end
+
+        def thinking_delta(text, &)
+          @current.text << text.to_s
+          emit_event(:thinking_delta, content_index: @current.index, delta: text, &)
+        end
+
+        def input_delta(fragment, &)
+          @current.json << fragment.to_s
+          emit_event(:toolcall_delta, content_index: @current.index, delta: fragment, &)
+        end
+
+        def stop_block(_record, &)
+          return unless @current
+
+          block = finalize_current
+          kind = block.is_a?(ToolCall) ? :toolcall : block.type
+          fields = { content_index: @blocks.size - 1 }
+          fields[:tool_call] = block if block.is_a?(ToolCall)
+          fields[:content] = @blocks.last.is_a?(ToolCall) ? nil : builder_text(block)
+          emit_event(:"#{kind}_end", **fields.compact, &)
+        end
+
+        def message_delta(record)
+          reason = record.dig("delta", "stop_reason")
+          @stop_reason = map_stop_reason(reason) if reason
+          # message_delta usage is cumulative; merge output counts over the
+          # opening snapshot rather than summing.
+          output = record.dig("usage", "output_tokens")
+          @usage = @usage.with(output: output.to_i) if output
+        end
+
+        def finalize_current
+          return unless @current
+
+          built = build_block(@current)
+          @blocks << built
+          @current = nil
+          built
+        end
+
+        def build_block(builder)
+          case builder.kind
+          when :text then Content::Text.new(text: builder.text)
+          when :thinking
+            Content::Thinking.new(thinking: builder.text, signature: builder.signature,
+                                  redacted: builder.redacted)
+          when :toolcall
+            ToolCall.new(id: builder.id, name: builder.name,
+                         arguments: parsed_arguments(builder.json), signature: nil)
+          end
+        end
+
+        def parsed_arguments(json)
+          parsed = json.strip.empty? ? {} : PartialJson.parse(json)
+          parsed.is_a?(Hash) ? parsed : {}
+        end
+
+        def builder_text(block)
+          block.respond_to?(:text) ? block.text : block.thinking
+        end
+
+        def emit_event(type, **fields, &emit)
+          emit&.call(Event.new(type:, partial: assemble, **fields))
+        end
+
+        def assemble(**meta)
+          blocks = @blocks.dup
+          blocks << build_block(@current) if @current
+          Message.assistant(content: blocks, model: @model, provider: :anthropic,
+                            usage: @usage, **meta)
+        end
+
+        # pause_turn (a server tool paused a long turn) maps to tool_use so the
+        # loop continues the turn rather than ending it.
+        def map_stop_reason(reason)
+          { "end_turn" => StopReason::STOP, "stop_sequence" => StopReason::STOP,
+            "max_tokens" => StopReason::LENGTH, "tool_use" => StopReason::TOOL_USE,
+            "pause_turn" => StopReason::TOOL_USE }.fetch(reason, StopReason::STOP)
+        end
+
+        def parse_usage(raw)
+          return Usage.zero unless raw
+
+          cache_creation = raw["cache_creation"] || {}
+          Usage.new(input: raw["input_tokens"].to_i, output: raw["output_tokens"].to_i,
+                    cache_read: raw["cache_read_input_tokens"].to_i,
+                    cache_write: raw["cache_creation_input_tokens"].to_i,
+                    cache_write_1h: cache_creation["ephemeral_1h_input_tokens"].to_i)
+        end
+      end
+    end
+  end
+end