mistri 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de242bfa63b5f170166c93613fc2a2807971d45b792a6200eb60805c4f41c977
-  data.tar.gz: 362d523bba1848e2b552ece5906b1554c4a54820379c9f8e7a3e93430144a9c1
+  metadata.gz: 820753fb8dd64f485da060568e6dbc8a7af3fa24d63a2cc7dc957b5dbfc9f1d6
+  data.tar.gz: c3e7432802801d19979c3d2906f700fbe3170a1d4950d22f0da88e01b276b905
 SHA512:
-  metadata.gz: 2ac330d28d201397f03912c893a538e824c5889a999f7afff3dde4cca8fe8e3a1263f4b886623f6c65fa6b732eae02962e72d4d9c6e945215f2aa724af1d82cb
-  data.tar.gz: fa27dd203af02953b311a479992e82f87e526c8b825b6be057ec0c4bffc0a76172b19af11e57ed7c522a15d0f8e063724b74dd5c5173f11118e96736457c4453
+  metadata.gz: 78959db170082e7264a3657dec0ff1e21ebf496a2e2603fe98ca6a7b263f68f980456df3f2881d798f2a8e7a296902700b2dc4e155a9ef43f54a32df5ca75eb7
+  data.tar.gz: 565be0a187d2651d92d43e59351090e0d6623dff13d70bbd1747e5c35f5167f162a4182c111e265734eadbc9aa465be003d5704da61495af281b321036eb0f26

data/CHANGELOG.md

@@ -5,6 +5,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-07-06
+
+- Terminal events are loop-owned: each attempt's :done or :error is held at
+  a gate and only the accepted attempt's terminal reaches the subscriber. A
+  transient failure that retries and recovers no longer shows the host an
+  error it then walks back, and repeated empty completions no longer emit a
+  :done per attempt.
+- The :retry event carries structure: attempt, max_attempts, and delay ride
+  the event (and its wire form), so a sink can render "Retrying (2/3) in
+  1.3s" without parsing prose. The prose note stays as content. The event
+  no longer carries a stop reason, because a retry is not a stop.
+- RetryPolicy owns attempt classification: error_for(message) returns the
+  provider's error or a synthesized EmptyCompletion for a blank answer.
+  RetryPolicy::EMPTY_COMPLETION replaces the agent-internal constant.
+- The MCP client advertises protocol 2025-11-25, the current spec revision
+  it already negotiated.
+- README: the :retry event and the terminal-events invariant are documented
+  in the reliability section; the MCP section documents eager listing,
+  refresh:, and the duplicate-name raise at Agent.new.
+
 ## [0.4.0] - 2026-07-05
 
 - Mistri::Definition: agents as frontmatter markdown files. Config in

data/README.md

@@ -304,6 +304,12 @@ tools = Mistri::MCP.tools(client, prefix: "linear",
 agent = Mistri.agent("claude-opus-4-8", tools: tools)
 ```
 
+The bridge lists the server's tools once, at build time; `client.tools(refresh: true)`
+re-lists when a host wants a changed toolset. `prefix:` namespaces local
+names (`linear__create_issue`) because duplicate tool names raise at
+`Agent.new`: collisions fail loud instead of one server's tool silently
+shadowing another's.
+
 Local stdio servers spawn as child processes, credentials in their
 environment. That is also the whole "give the agent a browser" story:
 
@@ -369,6 +375,23 @@ budget = Mistri::Budget.new(turns: 20, cost_usd: 2.00)
 policy = Mistri::RetryPolicy.new(attempts: 3)
 ```
 
+Retries are invisible to the model but not to your UI: each backoff emits a
+`:retry` event carrying `attempt`, `max_attempts`, and `delay`, so a sink can
+show a live "reconnecting" state instead of a silent spinner. Terminal events
+are loop-owned: `:done` and `:error` reach the subscriber only for the
+accepted attempt, so a recovered retry never flashes an error it then walks
+back.
+
+```ruby
+agent.run("Plan the itinerary.") do |event|
+  case event.type
+  when :text_delta then stream(event.delta)
+  when :retry then banner("Retrying (#{event.attempt}/#{event.max_attempts}) in #{event.delay}s")
+  when :done, :error then clear_banner
+  end
+end
+```
+
 ## Images and provider options
 
 ```ruby

data/lib/mistri/agent.rb

@@ -52,12 +52,6 @@ module Mistri
 
     attr_reader :session
 
-    # What retries see when a completion answers nothing at all.
-    EMPTY_COMPLETION_ERROR = {
-      "type" => "EmptyCompletion",
-      "message" => "the provider returned an empty completion"
-    }.freeze
-
     # Run one exchange: append the user turn, then loop until the model
     # answers without tools, a gated tool suspends the run, the run aborts,
     # or a budget stops it.
@@ -66,10 +60,12 @@ module Mistri
     # on top; run alone does not validate.
     def run(input, images: [], signal: nil, output_schema: nil, &emit)
       if @session.open_approvals.any?
-        raise ConfigurationError, "session is awaiting approval decisions; call resume"
+        raise ConfigurationError,
+              "session is awaiting approvals; call resume"
       end
       if input.to_s.empty? && Array(images).empty?
-        raise ArgumentError, "run needs input text or images"
+        raise ArgumentError,
+              "run needs input text or images"
       end
 
       fold_steers # steers queued while idle arrived first; keep that order
@@ -208,44 +204,35 @@ module Mistri
     # the request.
     #
     # A transient failure retries the same request with backoff; the failed
-    # attempt is recorded as a retry entry, never as a message, so retries
-    # stay invisible to the model. Only the final outcome persists.
+    # attempt records as a retry entry, never as a message, and its terminal
+    # (:done or :error) holds at a gate, so retries stay invisible to the
+    # model and a recovered retry never shows the subscriber an error it
+    # walks back. Only the accepted attempt persists and terminates.
     def run_turn(signal, output_schema = nil, &emit)
       history = @transform_context.reduce(@session.messages) do |messages, transform|
         transform.call(messages)
       end
       attempt = 0
       loop do
+        held = nil
+        gate = emit && ->(event) { event.terminal? ? held = event : emit.call(event) }
         message = @provider.stream(messages: history, system: @system,
                                    tools: @tools.map(&:spec), signal: signal,
-                                   output_schema: output_schema, &emit)
+                                   output_schema: output_schema, &gate)
         attempt += 1
-        error = turn_error(message)
+        error = @retries&.error_for(message)
         if retry_turn?(error, attempt, signal)
           pause = @retries.delay(attempt, error["retry_after"])
           record_retry(message, error, attempt, pause, &emit)
           wait(pause, signal)
           next unless signal&.aborted?
         end
+        emit&.call(held) if held
         @session.append_message(message)
         return message
       end
     end
 
-    # The provider's own error when the turn failed, or a synthesized one
-    # for a completion that answers nothing: providers intermittently stop
-    # with an empty candidate, and a retry usually clears it.
-    def turn_error(message)
-      return message.error if message.stop_reason == StopReason::ERROR
-
-      EMPTY_COMPLETION_ERROR if empty_completion?(message)
-    end
-
-    def empty_completion?(message)
-      message.stop_reason == StopReason::STOP &&
-        message.content.all? { |block| block.is_a?(Content::Text) && block.text.to_s.strip.empty? }
-    end
-
     def retry_turn?(error, attempt, signal)
       return false unless @retries && error
       return false if signal&.aborted?
@@ -258,7 +245,8 @@ module Mistri
                                "delay" => pause.round(2))
       note = format("attempt %<attempt>d failed; retrying in %<pause>.1fs",
                     attempt: attempt, pause: pause)
-      emit&.call(Event.new(type: :retry, content: note, reason: StopReason::ERROR,
+      emit&.call(Event.new(type: :retry, content: note, attempt: attempt,
+                           max_attempts: @retries.attempts, delay: pause.round(2),
                            message: message))
     end
 

data/lib/mistri/event.rb

@@ -15,11 +15,14 @@ module Mistri
   # events; nil where nothing ran (denials, interruptions).
   class Event < Data.define(:type, :content_index, :delta, :content, :tool_call,
                             :reason, :message, :error_message, :partial, :origin,
-                            :duration)
+                            :duration, :attempt, :max_attempts, :delay)
     # 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.
+    # 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
+    # accepted attempt's terminal event reaches the subscriber.
     TYPES = %i[
       start
       text_start text_delta text_end
@@ -33,7 +36,7 @@ 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)
+                   duration: nil, attempt: nil, max_attempts: nil, delay: nil)
       raise ArgumentError, "unknown event type #{type.inspect}" unless TYPES.include?(type)
 
       super
@@ -48,7 +51,8 @@ module Mistri
     # 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: }.compact
+        reason:, message: message&.to_h, error_message:, origin:, duration:,
+        attempt:, max_attempts:, delay: }.compact
     end
   end
 end

data/lib/mistri/mcp/client.rb

@@ -24,7 +24,7 @@ module Mistri
     # One client serializes its calls; parallel tool calls against one
     # server queue rather than interleave.
     class Client
-      PROTOCOL_VERSION = "2025-06-18"
+      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
 

data/lib/mistri/retry_policy.rb

@@ -21,10 +21,25 @@ module Mistri
       @max_delay = max_delay
     end
 
+    # What retries see when a completion answers nothing at all.
+    EMPTY_COMPLETION = {
+      "type" => "EmptyCompletion",
+      "message" => "the provider returned an empty completion"
+    }.freeze
+
     def retry?(error, attempt)
       attempt <= attempts && retryable?(error)
     end
 
+    # The error a finished attempt carries: the provider's own error, or a
+    # synthesized one for a completion that answers nothing at all, which a
+    # retry usually clears.
+    def error_for(message)
+      return message.error if message.stop_reason == StopReason::ERROR
+
+      EMPTY_COMPLETION if empty?(message)
+    end
+
     # error is the ErrorData hash from an errored message. A status decides
     # when present; otherwise only known-transient types retry, so schema
     # violations and host bugs never loop.
@@ -43,5 +58,12 @@ module Mistri
       exponential = base * (2**(attempt - 1))
       (exponential * rand(0.5..1.0)).clamp(0.0, max_delay)
     end
+
+    private
+
+    def empty?(message)
+      message.stop_reason == StopReason::STOP &&
+        message.content.all? { |block| block.is_a?(Content::Text) && block.text.to_s.strip.empty? }
+    end
   end
 end

data/lib/mistri/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mistri
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mistri
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Muhammad Ahmed Cheema