mistri 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e553e955f2a1263afed1b26889dbf04773916dbd6f33f9229e6db2b729dd655b
-  data.tar.gz: 98b95079d9f91b068580ac2708c362b1317452378eba99fe7643e301660ad89d
+  metadata.gz: 05f65dbeaf12ad0dc59334e300a2ecd2febc01607d528c0d8e7a95003c49e608
+  data.tar.gz: f1c261e05ee6e433f3b08f6c129841b6b25a44ee935671d3314681de792d0da5
 SHA512:
-  metadata.gz: cb690580fe35c2226bfa0d86d23f77c9236e8dcb10ba3af0a7753a1d52b96c11e951d41ee647d0cf947dae1d3c82ca834105070099dec0c4bac728bcd296698b
-  data.tar.gz: 9e5be1a7fde00c351abc5f123ddfa82db8cb0ae34f14b0c6aa474b12338c587958c547d68e70280de7cda780ea4e674953e0f28681d33c17b37edd8ea1672d8e
+  metadata.gz: 852c0bc7b87c7aa8b09b6862b88babbdbe3ddd6bd3e9736d8429818a3daaa98279fbe4f7703fd45e371ab78d7e76b0660ee19c47f183c760bcdba41d58bb6929
+  data.tar.gz: 2e97b19dfee548042488c16d4d37ddcdf5adf3959de7cd90d076e29c667021f2c07aec603eb8d6d0316ce944a027b55da9ca13f2adf3bc1647dac38b16316c0c

data/CHANGELOG.md

@@ -5,6 +5,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-05
+
+- Sessions heal at replay: a run killed mid-tool (deploy, crash) leaves
+  tool calls without results, which providers reject on every later turn.
+  Unsettled calls now replay with a synthesized interrupted result; calls
+  parked for human approval stay open for resume. The stored log is never
+  rewritten, and context assembly now reads the store exactly once.
+- Empty completions retry: a turn that answers with no text, thinking, or
+  tool calls (an intermittent provider behavior) now retries under the
+  standard policy instead of ending the run in silence.
+- Gemini: consecutive user turns are no longer merged. Mixing a text part
+  into a functionResponse turn makes Gemini answer an empty candidate, so
+  steers and resumed prompts stay their own turns; Gemini accepts this.
+- The spawn tool takes an optional `name`: the model labels each worker,
+  and the label rides origin tags and the transcript link, so fan-out
+  streams read as `pricing-scout#a41f` instead of `spawn#a41f`.
+- The spawn tool's `model` parameter names the default child model in its
+  description, so the model's choice (or non-choice) is informed.
+
 ## [0.2.1] - 2026-07-05
 
 - The gem homepage and documentation links now point at

data/README.md

@@ -7,6 +7,8 @@
 
 <p align="center"><strong>mistri</strong>, the agent harness for Ruby applications.</p>
 
+<p align="center"><a href="https://mistri.sh">mistri.sh</a> · <a href="https://mistri.sh/docs/getting-started/">docs</a></p>
+
 <p align="center">
   <a href="https://rubygems.org/gems/mistri"><img alt="Gem Version" src="https://img.shields.io/gem/v/mistri"></a>
   <a href="https://github.com/mcheemaa/mistri/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mcheemaa/mistri/actions/workflows/ci.yml/badge.svg"></a>
@@ -230,8 +232,9 @@ agent = Mistri.agent("claude-opus-4-8", tools: [researcher.tool])
 ```
 
 Or hand the model an open spawn tool and let it compose its own workers:
-instructions, a tool subset, and a host-allowlisted model per child.
-Several spawns in one turn fan out in parallel:
+a name for the event stream, instructions, a tool subset, and a
+host-allowlisted model per child. Several spawns in one turn fan out in
+parallel:
 
 ```ruby
 spawn = Mistri::SubAgent.spawner(provider: provider, tools: [fetch_page, search])
@@ -351,18 +354,21 @@ Mistri.agent("claude-opus-4-8", provider_options: { cache: false })
 ## Testing
 
 `rake test` is hermetic and fast. `rake integration` runs every feature end
-to end against real provider APIs, once per model in the matrix. Scenarios
-assert that coined codenames (a ghost of a word like `Wraithowyn` exists in
-no training data) flowed through tool results, summaries, and child agents:
-proof of information flow, not model knowledge.
+to end against real provider APIs, once per model in the matrix: an
+Anthropic, an OpenAI, and a Gemini model by default. Scenarios assert that
+coined codenames (a ghost of a word like `Wraithowyn` exists in no training
+data) flowed through tool results, summaries, and child agents: proof of
+information flow, not model knowledge.
 
 ```console
-$ MISTRI_INTEGRATION_MODELS=claude-opus-4-8,gpt-5.5 bundle exec rake integration
+$ bundle exec rake integration
+$ MISTRI_INTEGRATION_MODELS=claude-opus-4-8 bundle exec rake integration
 ```
 
 ## Roadmap
 
-`0.2.0`: an MCP client bridge, so any MCP server's tools plug into an agent.
+Next up: strict tool schemas, provider-native MCP passthrough, and the
+hardening that falls out of the first production applications.
 
 ## Credits
 

data/lib/mistri/agent.rb

@@ -50,6 +50,12 @@ 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.
@@ -212,9 +218,10 @@ module Mistri
                                    tools: @tools.map(&:spec), signal: signal,
                                    output_schema: output_schema, &emit)
         attempt += 1
-        if retry_turn?(message, attempt, signal)
-          pause = @retries.delay(attempt, message.error&.dig("retry_after"))
-          record_retry(message, attempt, pause, &emit)
+        error = turn_error(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
@@ -223,15 +230,29 @@ module Mistri
       end
     end
 
-    def retry_turn?(message, attempt, signal)
-      return false unless @retries && message.stop_reason == StopReason::ERROR
+    # 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?
 
-      @retries.retry?(message.error, attempt)
+      @retries.retry?(error, attempt)
     end
 
-    def record_retry(message, attempt, pause, &emit)
-      @session.append("retry", "attempt" => attempt, "error" => message.error,
+    def record_retry(message, error, attempt, pause, &emit)
+      @session.append("retry", "attempt" => attempt, "error" => error,
                                "delay" => pause.round(2))
       note = format("attempt %<attempt>d failed; retrying in %<pause>.1fs",
                     attempt: attempt, pause: pause)

data/lib/mistri/providers/gemini/serializer.rb

@@ -10,26 +10,17 @@ module Mistri
       # thought signatures echo back verbatim on the exact part they arrived
       # with, but only for messages this provider produced; a foreign
       # signature would be rejected. Thinking summaries are output-only and
-      # never replay.
+      # never replay. Consecutive user turns stay separate: Gemini accepts
+      # them, and mixing a text part into a functionResponse turn makes it
+      # answer an empty candidate.
       module Serializer
         module_function
 
         def contents(history)
           groups = history.reject(&:system?).chunk_while { |a, b| a.tool? && b.tool? }
-          turns = groups.filter_map do |group|
+          groups.filter_map do |group|
             group.first.tool? ? tool_turn(group) : turn(group.first)
           end
-          merge_user_runs(turns)
-        end
-
-        # A steered run puts a user message right behind tool results, and
-        # both serialize as user turns. Gemini expects turns to alternate, so
-        # consecutive user turns merge into one.
-        def merge_user_runs(turns)
-          turns.chunk_while { |a, b| a[:role] == "user" && b[:role] == "user" }
-               .map do |run|
-            run.length == 1 ? run.first : { role: "user", parts: run.flat_map { |t| t[:parts] } }
-          end
         end
 
         def system_instruction(system)

data/lib/mistri/retry_policy.rb

@@ -11,7 +11,7 @@ module Mistri
   class RetryPolicy
     RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504, 529].freeze
     RETRYABLE_TYPES = %w[ProviderError RateLimitError OverloadedError ServerError
-                         TruncatedStream].freeze
+                         TruncatedStream EmptyCompletion].freeze
 
     attr_reader :attempts, :base, :max_delay
 

data/lib/mistri/session.rb

@@ -40,16 +40,25 @@ module Mistri
     # The conversation as the model replays it.
     def messages = replay.map(&:first)
 
+    # What a run killed mid-tool answers in place of the result it never got.
+    INTERRUPTED_RESULT = "[interrupted: the run stopped before this tool returned]"
+
     # Replay messages paired with the entry index each came from, starting at
     # the latest compaction boundary. The synthetic summary message carries a
     # nil index. Compaction places its cuts by these indexes; the full entry
-    # log stays in the store for transcript views.
+    # log stays in the store for transcript views. One store read builds the
+    # whole context, healed: a crash that left tool calls unanswered would
+    # brick every later turn with a provider rejection, so unsettled calls
+    # get a synthesized interrupted result. Calls parked for human approval
+    # stay open; resume owns those.
     def replay
-      compaction = last_compaction
+      log = entries
+      compaction = log.reverse_each.find { |entry| entry["type"] == "compaction" }
       from = compaction ? compaction["kept_from"] : 0
-      pairs = entries.each_with_index.filter_map do |entry, index|
+      pairs = log.each_with_index.filter_map do |entry, index|
         [Message.from_h(entry["message"]), index] if index >= from && entry["type"] == "message"
       end
+      pairs = heal(pairs, parked_call_ids(log))
       compaction ? [[summary_message(compaction["summary"]), nil], *pairs] : pairs
     end
 
@@ -102,6 +111,28 @@ module Mistri
 
     private
 
+    def heal(pairs, parked)
+      answered = pairs.map(&:first).select(&:tool?).to_set(&:tool_call_id)
+      pairs.flat_map do |message, index|
+        dangling = if message.assistant?
+                     message.tool_calls.reject do |call|
+                       answered.include?(call.id) || parked.include?(call.id)
+                     end
+                   else
+                     []
+                   end
+        [[message, index]] + dangling.map do |call|
+          [Message.tool(content: INTERRUPTED_RESULT, tool_call_id: call.id,
+                        tool_name: call.name), nil]
+        end
+      end
+    end
+
+    def parked_call_ids(log)
+      log.filter_map { |entry| entry.dig("call", "id") if entry["type"] == "approval_request" }
+         .to_set
+    end
+
     def summary_message(summary)
       Message.user("#{Compaction::SUMMARY_PREFACE}\n\n#{summary}")
     end

data/lib/mistri/sub_agent.rb

@@ -18,8 +18,8 @@ module Mistri
   #   )
   #   agent = Mistri::Agent.new(provider:, tools: [researcher.tool])
   #
-  # and the open spawn tool, where the model writes the child's
-  # instructions, picks a tool subset, and may name a model:
+  # and the open spawn tool, where the model composes each worker: names
+  # it, writes its instructions, picks a tool subset, and may pick a model:
   #
   #   spawn = Mistri::SubAgent.spawner(provider:, tools: [fetch_page, search])
   #
@@ -84,9 +84,10 @@ module Mistri
 
     class << self
       # The open spawn tool over a pool of tools the host allows children to
-      # use. The model may grant a tool subset by name; models: is the
-      # host's allowlist of child model ids — without one, no model choice
-      # is offered at all, so a hallucinated id can never construct a
+      # use. The model may name the worker (a display label riding origins
+      # and the transcript link) and grant a tool subset by name; models: is
+      # the host's allowlist of child model ids — without one, no model
+      # choice is offered at all, so a hallucinated id can never construct a
       # provider or land children on an expensive model.
       def spawner(provider:, tools: [], models: [], needs_approval: false, **agent_options)
         forbid_gated!(tools)
@@ -94,10 +95,11 @@ module Mistri
           raise ConfigurationError, "the spawn tool never goes in its own pool"
         end
 
+        schema = spawner_schema(tools, models, default_model(provider))
         Tool.define("spawn_agent", SPAWNER_DESCRIPTION,
-                    needs_approval: needs_approval,
-                    schema: spawner_schema(tools, models)) do |args, context|
-          run_child(label: "spawn", provider: child_provider(provider, args["model"], models),
+                    needs_approval: needs_approval, schema: schema) do |args, context|
+          run_child(label: child_label(args["name"]),
+                    provider: child_provider(provider, args["model"], models),
                     system: args.fetch("instructions"),
                     tools: pick(tools, args["tools"]),
                     task: args.fetch("task"), context: context, **agent_options)
@@ -173,22 +175,33 @@ module Mistri
         end
       end
 
-      def spawner_schema(pool, models)
+      def spawner_schema(pool, models, default)
         tool_names = pool.map(&:name)
+        fallback = default ? " (default: #{default})" : ""
         lambda do
+          string :name, "A short name for this worker, shown wherever its events appear"
           string :task, "The child's complete task", required: true
           string :instructions, "The child's system prompt", required: true
           if tool_names.any?
             array :tools, "Subset of tools to grant (default: all)",
                   items: { type: "string", enum: tool_names }
           end
-          if models.any?
-            string :model, "Model for the child (default: the configured one)",
-                   enum: models
-          end
+          string :model, "Model for the child#{fallback}", enum: models if models.any?
         end
       end
 
+      def default_model(provider)
+        provider.model if provider.respond_to?(:model)
+      end
+
+      # The label rides origins as "label#id" and joins nesting with ">",
+      # so those separators squeeze to hyphens along with whitespace.
+      def child_label(raw)
+        label = raw.to_s.gsub(/[#>\s]+/, "-").squeeze("-")[0, 32]
+        label = label.delete_prefix("-").delete_suffix("-")
+        label.empty? ? "spawn" : label
+      end
+
       def child_provider(default, requested, models)
         return default if requested.nil? || requested.to_s.empty?
         unless models.include?(requested)

data/lib/mistri/version.rb

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

metadata

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