mistri 0.5.0 → 0.6.0

data/lib/mistri/event.rb

@@ -11,15 +11,18 @@ module Mistri
   # 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").
-  # duration is the tool's execution time in seconds on :tool_result
-  # events; nil where nothing ran (denials, interruptions).
+  # duration is the measured tool execution time on :tool_result events; nil
+  # means no duration is available, not necessarily that no side effect ran.
+  # tool_error is explicit on :tool_result and does not change Event#error?,
+  # which means a terminal provider-turn failure.
   class Event < Data.define(:type, :content_index, :delta, :content, :tool_call,
                             :reason, :message, :error_message, :partial, :origin,
                             :duration, :attempt, :max_attempts, :delay,
-                            :agent, :session_id, :status)
+                            :agent, :session_id, :status, :tool_error)
     # 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, :compacting/:compaction around a context
+    # :tool_started when a resolved tool commits to execution, :tool_result
+    # after it finishes, :approval_needed when a gated call parks for a human,
+    # :compacting/:compaction around a context
     # compaction, and :retry (with attempt, max_attempts, delay) before it
     # waits out a transient failure, so one subscription sees the whole
     # exchange. :done and :error are loop-owned and terminal: only the
@@ -33,7 +36,7 @@ module Mistri
       thinking_start thinking_delta thinking_end
       toolcall_start toolcall_delta toolcall_end
       done error
-      tool_result approval_needed
+      tool_started tool_result approval_needed
       compacting compaction
       retry
       subagent_report
@@ -42,9 +45,20 @@ module Mistri
     def initialize(type:, content_index: nil, delta: nil, content: nil, tool_call: nil,
                    reason: nil, message: nil, error_message: nil, partial: nil, origin: nil,
                    duration: nil, attempt: nil, max_attempts: nil, delay: nil,
-                   agent: nil, session_id: nil, status: nil)
+                   agent: nil, session_id: nil, status: nil, tool_error: nil)
       raise ArgumentError, "unknown event type #{type.inspect}" unless TYPES.include?(type)
 
+      if type == :tool_result
+        unless [true, false].include?(tool_error)
+          raise ArgumentError, "tool_result events require a boolean tool_error"
+        end
+      elsif !tool_error.nil?
+        raise ArgumentError, "tool_error is only valid on tool_result events"
+      end
+      if type == :tool_result && message && message.tool_error != tool_error
+        raise ArgumentError, "event tool_error must match its message"
+      end
+
       super
     end
 
@@ -52,13 +66,15 @@ module Mistri
 
     def error? = type == :error
 
+    def tool_error? = tool_error == true
+
     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:, duration:,
-        attempt:, max_attempts:, delay:, agent:, session_id:, status: }.compact
+        attempt:, max_attempts:, delay:, agent:, session_id:, status:, tool_error: }.compact
     end
   end
 end

data/lib/mistri/event_delivery.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Mistri
+  # Preserves subscriber exception identity across internal rescue boundaries.
+  module EventDelivery
+    # Tags a subscriber failure with the boundary that first observed it.
+    class Failure < StandardError
+      attr_reader :original, :boundary
+
+      def initialize(original, boundary)
+        @original = original
+        @boundary = boundary
+        super(original.message)
+        set_backtrace(original.backtrace)
+      end
+    end
+
+    # Wraps one subscriber and unwraps only failures that it created.
+    class Boundary
+      def initialize(subscriber, passthrough: [])
+        @subscriber = subscriber
+        @passthrough = passthrough.freeze
+        @callable = method(:call).to_proc
+      end
+
+      def to_proc = @callable
+
+      def call(event)
+        @subscriber.call(event)
+      rescue Failure
+        raise
+      rescue StandardError => e
+        raise if @passthrough.any? { |error_class| e.is_a?(error_class) }
+
+        raise Failure.new(e, self)
+      end
+
+      def unwrap(error)
+        error.boundary.equal?(self) ? error.original : error
+      end
+    end
+
+    module_function
+
+    def wrap(subscriber, passthrough: [])
+      Boundary.new(subscriber, passthrough: passthrough) if subscriber
+    end
+
+    def unwrap(error, boundary)
+      return error unless error.is_a?(Failure) && boundary
+
+      boundary.unwrap(error)
+    end
+
+    def original(error)
+      error.is_a?(Failure) ? error.original : error
+    end
+  end
+  private_constant :EventDelivery
+end

data/lib/mistri/locks.rb

@@ -6,15 +6,15 @@ module Mistri
   # Cross-process coordination for hosts that run loops in more than one
   # process: leases that say "this is alive right now" and flags that carry
   # one-bit requests (stop) between processes. Everything expires on its
-  # own, so a crashed holder never wedges anything; a live holder renews on
-  # a heartbeat, so only dead ones expire.
+  # own, so a crashed holder never wedges anything; a healthy holder renews
+  # on a heartbeat, while a stalled process can still outlive its lease.
   #
   # Configure once at boot:
   #
   #   Mistri.locks = Mistri::Locks::Memory.new          # single process
   #   Mistri.locks = Mistri::Locks::RailsCache.new      # requires opt-in file
   #
-  # An adapter implements six methods: acquire(key, ttl:) -> bool,
+  # An adapter implements seven methods: acquire(key, ttl:) -> bool,
   # renew(key, ttl:), release(key), held?(key), set_flag(key, ttl:),
   # flag?(key), clear_flag(key). With no adapter configured, everything
   # lease-aware degrades gracefully: children read :running instead of

data/lib/mistri/mcp/client.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "uri"
-
 module Mistri
   module MCP
     # A Model Context Protocol client: the initialize handshake, tools/list
@@ -20,37 +18,45 @@ module Mistri
     # re-resolving, so a host's refresh logic lives in one lambda. A session
     # the server expires (404 with a session attached) transparently
     # re-initializes, per spec.
+    # Remote URLs default to public HTTPS. allow_non_public: is consulted only
+    # for otherwise blocked addresses and plain HTTP remains loopback-only.
+    # max_record_bytes bounds one JSON body, SSE line, or stdio record without
+    # imposing a lifetime limit on an SSE stream.
     #
     # One client serializes its calls; parallel tool calls against one
     # server queue rather than interleave.
     class Client
       PROTOCOL_VERSION = "2025-11-25"
       SUPPORTED_VERSIONS = %w[2025-11-25 2025-06-18 2025-03-26 2024-11-05].freeze
-      LOOPBACK = %w[localhost 127.0.0.1 ::1].freeze
-
       attr_reader :server_info
 
       def initialize(url: nil, command: nil, env: {}, token: nil, headers: {},
-                     client_name: "mistri", open_timeout: 15, read_timeout: 120)
+                     client_name: "mistri", open_timeout: 15, read_timeout: 120,
+                     allow_non_public: nil, max_tool_pages: 100, max_tools: 10_000,
+                     max_record_bytes: DEFAULT_MAX_RECORD_BYTES)
         if [url, command].compact.length != 1
           raise ConfigurationError, "pass exactly one of url: or command:"
         end
 
-        if url && token && URI(url).scheme == "http" && !LOOPBACK.include?(URI(url).host)
-          raise ConfigurationError,
-                "refusing to send a bearer token over plain HTTP to #{URI(url).host}"
-        end
+        validate_limit(:max_tool_pages, max_tool_pages)
+        validate_limit(:max_tools, max_tools)
+        validate_limit(:max_record_bytes, max_record_bytes)
 
         @wire = if url
                   Wires::Http.new(url: url, token: token, headers: headers,
-                                  open_timeout: open_timeout, read_timeout: read_timeout)
+                                  open_timeout: open_timeout, read_timeout: read_timeout,
+                                  allow_non_public: allow_non_public,
+                                  max_record_bytes: max_record_bytes)
                 else
-                  Wires::Stdio.new(command: command, env: env, read_timeout: read_timeout)
+                  Wires::Stdio.new(command: command, env: env, read_timeout: read_timeout,
+                                   max_record_bytes: max_record_bytes)
                 end
         @client_name = client_name
         @mutex = Mutex.new
         @serial = 0
         @connected = false
+        @max_tool_pages = max_tool_pages
+        @max_tools = max_tools
       end
 
       # The server's tools as it describes them: hashes with "name",
@@ -72,8 +78,7 @@ module Mistri
       end
 
       def close
-        @wire.close
-        @connected = false
+        @mutex.synchronize { reset_wire }
         nil
       end
 
@@ -96,6 +101,9 @@ module Mistri
         @server_info = result["serverInfo"]
         @wire.notify({ jsonrpc: "2.0", method: "notifications/initialized" })
         @connected = true
+      rescue Mistri::Error
+        reset_wire
+        raise
       end
 
       def request(method, params, reconnected: false, refreshed: false)
@@ -119,7 +127,9 @@ module Mistri
         payload = { jsonrpc: "2.0", id: id, method: method, params: params }
         result = nil
         responded = false
-        @wire.call(payload) do |record|
+        replayable = method != "tools/call"
+        # A tool may commit its external side effect before the connection dies.
+        @wire.call(payload, replayable: replayable) do |record|
           next unless record.is_a?(Hash) && record["id"] == id
 
           responded = true
@@ -127,9 +137,28 @@ module Mistri
 
           result = record["result"]
         end
-        raise Error, "the server sent no response to #{method}" unless responded
+        unless responded
+          detail = "the server sent no matching response to #{method}"
+          raise Error, detail if replayable
+
+          raise AmbiguousDeliveryError, "#{AmbiguousDeliveryError.default_message}: #{detail}"
+        end
 
         result
+      rescue ResponseTooLargeError, ResponseTooComplexError, WireError => e
+        reset_wire
+        raise if replayable
+        return result if responded
+
+        message = "the request was sent but its tool outcome could not be confirmed: " \
+                  "#{e.message}; the operation may have completed; do not retry automatically; " \
+                  "verify external state first"
+        raise AmbiguousDeliveryError, message
+      rescue AmbiguousDeliveryError
+        reset_wire
+        return result if responded
+
+        raise
       rescue ProviderError => e
         raise SessionExpired if e.status == 404 && @wire.session?
 
@@ -139,13 +168,39 @@ module Mistri
       def list_tools
         collected = []
         cursor = nil
-        loop do
+        seen_cursors = {}
+        @max_tool_pages.times do
           result = request("tools/list", cursor ? { cursor: cursor } : {})
-          collected.concat(Array(result["tools"]))
+          raise Error, "tools/list returned a malformed result" unless result.is_a?(Hash)
+
+          page = result["tools"]
+          raise Error, "tools/list returned a malformed tools collection" unless page.is_a?(Array)
+          if collected.length + page.length > @max_tools
+            raise Error, "tool discovery exceeded #{@max_tools} tools"
+          end
+
+          collected.concat(page)
           cursor = result["nextCursor"]
-          break unless cursor
+          return collected if cursor.nil?
+          raise Error, "tools/list returned a malformed cursor" unless cursor.is_a?(String)
+          raise Error, "tools/list repeated a cursor" if seen_cursors[cursor]
+
+          seen_cursors[cursor] = true
         end
-        collected
+        raise Error, "tool discovery exceeded #{@max_tool_pages} pages"
+      end
+
+      def validate_limit(name, value)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise ConfigurationError, "#{name}: must be a positive integer"
+      end
+
+      def reset_wire
+        @wire.close
+        @wire.reset_session
+        @connected = false
+        @server_info = nil
       end
 
       def rpc_error(error)

data/lib/mistri/mcp/egress.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "socket"
+require "timeout"
+require "uri"
+
+module Mistri
+  module MCP
+    # Resolves untrusted MCP URLs onto globally reachable addresses and pins
+    # that decision to the eventual connection. A host may narrowly approve a
+    # non-public address, but cannot bypass URL shape or plaintext rules.
+    module Egress
+      Target = Data.define(:uri, :address)
+      NAT64_WELL_KNOWN = IPAddr.new("64:ff9b::/96")
+      IPV6_GLOBAL_UNICAST = IPAddr.new("2000::/3")
+
+      # IANA IPv4/IPv6 Special-Purpose Address Registries, updated 2025-10-09.
+      # Broad non-global ranges contain a few globally reachable assignments.
+      # https://www.iana.org/assignments/iana-ipv4-special-registry/
+      # https://www.iana.org/assignments/iana-ipv6-special-registry/
+      # https://www.iana.org/assignments/ipv6-address-space/
+      GLOBAL_EXCEPTIONS = %w[
+        192.0.0.9/32
+        192.0.0.10/32
+        192.31.196.0/24
+        192.52.193.0/24
+        192.175.48.0/24
+        2001:1::1/128
+        2001:1::2/128
+        2001:1::3/128
+        2001:3::/32
+        2001:4:112::/48
+        2001:20::/28
+        2001:30::/28
+        2620:4f:8000::/48
+      ].map { |range| IPAddr.new(range) }.freeze
+
+      NON_GLOBAL = %w[
+        0.0.0.0/8
+        10.0.0.0/8
+        100.64.0.0/10
+        127.0.0.0/8
+        169.254.0.0/16
+        172.16.0.0/12
+        192.0.0.0/24
+        192.0.2.0/24
+        192.88.99.0/24
+        192.168.0.0/16
+        198.18.0.0/15
+        198.51.100.0/24
+        203.0.113.0/24
+        224.0.0.0/4
+        240.0.0.0/4
+        ::/96
+        64:ff9b:1::/48
+        100::/64
+        100:0:0:1::/64
+        2001::/23
+        2001:db8::/32
+        2002::/16
+        3fff::/20
+        5f00::/16
+        fc00::/7
+        fe80::/10
+        fec0::/10
+        ff00::/8
+      ].map { |range| IPAddr.new(range) }.freeze
+
+      module_function
+
+      def target(url, allow_non_public: nil, label: "URL", timeout: 15, lookup: nil)
+        targets(url, allow_non_public:, label:, timeout:, lookup:).first
+      end
+
+      def targets(url, allow_non_public: nil, label: "URL", timeout: 15, lookup: nil)
+        uri, address_resolver = resolver(url, allow_non_public:, label:, timeout:, lookup:)
+        address_resolver.call.map { |address| Target.new(uri:, address:) }
+      end
+
+      def resolver(url, allow_non_public: nil, label: "URL", timeout: 15, lookup: nil)
+        validate_exception(allow_non_public)
+        uri = normalize(url, label)
+        if uri.scheme == "http" && allow_non_public.nil?
+          raise UnsafeURLError, "#{label} must use HTTPS"
+        end
+
+        snapshot = uri.to_s.freeze
+        resolve_addresses = lambda do
+          target = URI(snapshot)
+          addresses = resolve(target, label, timeout, lookup: lookup)
+          approved_addresses(target, addresses, allow_non_public:, label:)
+            .map(&:to_s).freeze
+        end
+        [URI(snapshot), resolve_addresses]
+      end
+
+      def approved_addresses(uri, addresses, allow_non_public: nil, label: "URL")
+        validate_exception(allow_non_public)
+        if addresses.empty?
+          raise UnsafeURLError,
+                "#{label} host #{uri.hostname.inspect} resolved to no addresses"
+        end
+        rejected = addresses.reject do |address|
+          policy_uri = URI(uri.to_s).freeze
+          policy_address = address.dup.freeze
+          globally_reachable?(address) || allow_non_public&.call(policy_uri, policy_address)
+        end
+        unless rejected.empty?
+          raise UnsafeURLError,
+                "#{label} host #{uri.hostname.inspect} resolves to a non-public address"
+        end
+        if uri.scheme == "http" && !addresses.all?(&:loopback?)
+          raise UnsafeURLError, "#{label} must use HTTPS"
+        end
+
+        addresses
+      end
+
+      def approved_address(uri, addresses, allow_non_public: nil, label: "URL")
+        approved_addresses(uri, addresses, allow_non_public:, label:).first
+      end
+
+      def normalize(url, label = "URL")
+        uri = parse(url, label)
+        uri.scheme = uri.scheme.downcase
+        uri.host = uri.host.downcase
+        uri.port = nil if uri.port == uri.default_port
+        uri.path = "" if uri.path == "/"
+        uri
+      rescue URI::Error, ArgumentError
+        raise UnsafeURLError, "#{label} must be an absolute HTTP(S) URL"
+      end
+
+      def redirect_uri(url)
+        value = url.to_s
+        uri = parse(value, "redirect_uri")
+        return value if uri.scheme == "https"
+
+        address = parse_address(uri.hostname)
+        return value if uri.hostname.casecmp?("localhost") || address&.loopback?
+
+        raise UnsafeURLError, "redirect_uri must use HTTPS or an explicit loopback address"
+      end
+
+      def origin(uri)
+        value = uri.dup
+        value.path = ""
+        value.query = nil
+        value.to_s
+      end
+
+      def display(uri)
+        value = uri.dup
+        value.query = nil
+        value.to_s
+      end
+
+      def globally_reachable?(address)
+        address = address.native if address.ipv4_mapped?
+        if NAT64_WELL_KNOWN.include?(address)
+          embedded = IPAddr.new(address.to_i & 0xffffffff, Socket::AF_INET)
+          return globally_reachable?(embedded)
+        end
+        return true if GLOBAL_EXCEPTIONS.any? { |range| range.include?(address) }
+        return false if address.ipv6? && !IPV6_GLOBAL_UNICAST.include?(address)
+
+        NON_GLOBAL.none? { |range| range.include?(address) }
+      end
+
+      def resolve(uri, label, timeout, lookup: nil)
+        lookup ||= Addrinfo.method(:getaddrinfo)
+        entries = lookup.call(uri.hostname, uri.port, nil, :STREAM, timeout: timeout)
+        found = entries.filter_map do |entry|
+          address = parse_address(entry.ip_address)
+          address&.ipv4_mapped? ? address.native : address
+        end.uniq
+        if found.empty?
+          raise UnsafeURLError,
+                "#{label} host #{uri.hostname.inspect} resolved to no addresses"
+        end
+
+        found
+      rescue SocketError, IOError, Timeout::Error
+        raise UnsafeURLError, "#{label} host #{uri.hostname.inspect} could not be resolved"
+      end
+
+      def parse_address(value)
+        IPAddr.new(value)
+      rescue IPAddr::Error
+        nil
+      end
+
+      def validate_exception(exception)
+        return if exception.nil? || exception.respond_to?(:call)
+
+        raise ConfigurationError, "allow_non_public: must be callable"
+      end
+
+      def parse(url, label)
+        uri = URI.parse(url.to_s)
+        unless uri.is_a?(URI::HTTP) && %w[http https].include?(uri.scheme) &&
+               !uri.hostname.to_s.empty?
+          raise UnsafeURLError, "#{label} must be an absolute HTTP(S) URL"
+        end
+        raise UnsafeURLError, "#{label} must not contain credentials" if uri.user || uri.password
+        raise UnsafeURLError, "#{label} must not contain a fragment" if uri.fragment
+        raise UnsafeURLError, "#{label} has an invalid port" unless (1..65_535).cover?(uri.port)
+
+        uri
+      rescue URI::Error, ArgumentError
+        raise UnsafeURLError, "#{label} must be an absolute HTTP(S) URL"
+      end
+    end
+  end
+end