mistri 0.4.0 → 0.5.0

data/lib/mistri/dispatchers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Mistri
+  # How a background child actually executes. The spawn tool hands every
+  # dispatcher two things: the serializable spec (name, session_id,
+  # parent_session_id, type, instructions, tool_names, model, workspace,
+  # task) and a runner closure that executes the child in this process with
+  # everything already reconstructed.
+  #
+  # In-process dispatchers just call the runner. A queue dispatcher ignores
+  # the runner, enqueues the spec, and its job reconstructs the pieces from
+  # host registries and calls SubAgent.run_dispatched:
+  #
+  #   dispatcher: ->(spec, _runner) { ChildRunJob.perform_async(spec) }
+  #
+  # The runner closes over the spawn-time event sink, so in-process
+  # children keep streaming to whoever watched the spawn; that sink must
+  # outlive the parent's turn (a broadcast lambda does, a request-scoped
+  # object may not).
+  module Dispatchers
+    # Runs the child synchronously inside the spawn call and still answers
+    # in receipt form: background degrades gracefully where no concurrency
+    # exists (consoles, tests), and the receipt stays truthful because it
+    # reads the child's status after dispatch.
+    class Inline
+      def call(_spec, runner) = runner.call
+    end
+
+    # Real in-process background: the child runs on its own thread and the
+    # spawn call returns immediately. Enough for development and for hosts
+    # whose children are short; queue-backed hosts plug their own lambda.
+    class Thread
+      def call(spec, runner)
+        ::Thread.new do
+          runner.call
+        rescue StandardError => e
+          # The runner writes the child's failed terminal before re-raising;
+          # a thread must not die loudly into the process, but it must not
+          # die silently either, or there is no trace to debug from.
+          warn "mistri: background runner for #{spec["name"].inspect} crashed: " \
+               "#{e.class}: #{e.message}"
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/mistri/event.rb

@@ -15,11 +15,18 @@ 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,
+                            :agent, :session_id, :status)
     # 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.
+    # :subagent_report announces a background child's terminal outcome
+    # (agent, session_id, status; content carries the report), so a UI that
+    # watched the spawn can settle the child's lane the moment it ends.
     TYPES = %i[
       start
       text_start text_delta text_end
@@ -29,11 +36,13 @@ module Mistri
       tool_result approval_needed
       compacting compaction
       retry
+      subagent_report
     ].freeze
 
     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,
+                   agent: nil, session_id: nil, status: nil)
       raise ArgumentError, "unknown event type #{type.inspect}" unless TYPES.include?(type)
 
       super
@@ -48,7 +57,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:, agent:, session_id:, status: }.compact
     end
   end
 end

data/lib/mistri/locks/rails_cache.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Opt-in, exactly like Stores::ActiveRecord: the gem never requires Rails.
+# require "mistri/locks/rails_cache".
+module Mistri
+  module Locks
+    # Leases and flags over an ActiveSupport::Cache::Store (Redis-backed in
+    # any real deployment), so every process in the fleet reads the same
+    # truth. Pass any cache store duck; defaults to Rails.cache.
+    class RailsCache
+      def initialize(cache: nil, namespace: "mistri:locks")
+        @cache = cache || (defined?(Rails) && Rails.cache) ||
+                 raise(ConfigurationError, "no cache store; pass cache: or configure Rails.cache")
+        @namespace = namespace
+      end
+
+      def acquire(key, ttl:)
+        @cache.write(scoped(key), true, unless_exist: true, expires_in: ttl)
+      end
+
+      def renew(key, ttl:)
+        @cache.write(scoped(key), true, expires_in: ttl)
+        nil
+      end
+
+      def release(key)
+        @cache.delete(scoped(key))
+        nil
+      end
+
+      def held?(key)
+        @cache.exist?(scoped(key))
+      end
+
+      def set_flag(key, ttl: 300)
+        renew(key, ttl: ttl)
+      end
+
+      def flag?(key) = held?(key)
+
+      def clear_flag(key) = release(key)
+
+      private
+
+      def scoped(key) = "#{@namespace}:#{key}"
+    end
+  end
+end

data/lib/mistri/locks.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+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.
+  #
+  # 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,
+  # 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
+  # :interrupted, and holds are no-ops.
+  module Locks
+    LEASE_TTL = 180
+    HEARTBEAT = 60
+
+    module_function
+
+    # Hold a lease for the duration of a block of work: acquire, renew on a
+    # heartbeat from a background thread, release on the way out. Returns a
+    # Hold to release in an ensure, or nil when no adapter is configured or
+    # the lease is already held elsewhere: a caller that was refused must
+    # never renew or delete the real holder's key. Callers that need to
+    # tell refusal apart from no-adapter use the adapter's acquire directly.
+    #
+    # With stop_key: and signal:, the same thread watches the flag and trips
+    # the signal within a tick, so a stop request written in another process
+    # becomes this run's cooperative abort.
+    def hold(key, ttl: LEASE_TTL, heartbeat: HEARTBEAT, stop_key: nil, signal: nil)
+      adapter = Mistri.locks
+      return nil unless adapter
+      return nil unless adapter.acquire(key, ttl: ttl)
+
+      Hold.new(adapter, key, ttl, heartbeat, stop_key: stop_key, signal: signal)
+    end
+
+    # A held lease: one thread renews it on the heartbeat and watches the
+    # stop flag between renewals. Renewal runs on a monotonic deadline (the
+    # last sleep before it is the remaining fraction, never a full tick, so
+    # the cadence is exact and a lease can never lapse waiting for a tick to
+    # round up). release stops the thread (and joins it, so a mid-renewal
+    # tick can never re-stamp a lease that was just released) and deletes
+    # the key.
+    class Hold
+      def initialize(adapter, key, ttl, heartbeat, stop_key: nil, signal: nil)
+        @adapter = adapter
+        @key = key
+        @stopping = false
+        @thread = Thread.new do
+          deadline = now + heartbeat
+          until @stopping
+            sleep (deadline - now).clamp(0.01, 1.0)
+            break if @stopping
+
+            signal.abort!("stopped by user") if stop_key && signal && adapter.flag?(stop_key)
+            if now >= deadline
+              adapter.renew(key, ttl: ttl)
+              deadline = now + heartbeat
+            end
+          end
+        end
+      end
+
+      def release
+        @stopping = true
+        @thread.kill
+        @thread.join(2)
+        @adapter.release(@key)
+      end
+
+      private
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # The in-process adapter: real TTL semantics over a hash, for tests,
+    # development, and the thread dispatcher. Monitor-synchronized; expiry
+    # is judged at read time, so nothing needs a sweeper.
+    class Memory
+      def initialize
+        @entries = {}
+        @lock = Monitor.new
+      end
+
+      def acquire(key, ttl:)
+        @lock.synchronize do
+          return false if live?(key)
+
+          @entries[key] = deadline(ttl)
+          true
+        end
+      end
+
+      def renew(key, ttl:)
+        @lock.synchronize { @entries[key] = deadline(ttl) }
+        nil
+      end
+
+      def release(key)
+        @lock.synchronize { @entries.delete(key) }
+        nil
+      end
+
+      def held?(key)
+        @lock.synchronize { live?(key) }
+      end
+
+      def set_flag(key, ttl: 300)
+        renew(key, ttl: ttl)
+      end
+
+      def flag?(key) = held?(key)
+
+      def clear_flag(key) = release(key)
+
+      private
+
+      def live?(key)
+        deadline = @entries[key]
+        return false unless deadline
+        return true if deadline > now
+
+        @entries.delete(key)
+        false
+      end
+
+      def deadline(ttl) = now + ttl
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    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/mcp.rb

@@ -5,7 +5,7 @@ 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
+  # 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",

data/lib/mistri/providers/fake.rb

@@ -67,18 +67,32 @@ module Mistri
         kind == :text ? Content::Text.new(text:) : Content::Thinking.new(thinking: text)
       end
 
+      # Arguments stream in chunks, and every delta's partial carries the
+      # in-progress call with the arguments parsed so far, the same shape a
+      # real assembler builds, so a consumer that renders tool input as it
+      # arrives (a page preview, a code block) is testable headless.
       def stream_tool_call(spec, position, blocks, emit)
         spec = spec.transform_keys(&:to_sym)
         call = ToolCall.new(id: spec[:id] || "call_#{position + 1}", name: spec[:name],
                             arguments: (spec[:arguments] || {}).transform_keys(&:to_s))
         index = blocks.size
         emit_event(emit, :toolcall_start, blocks, content_index: index)
-        emit_event(emit, :toolcall_delta, blocks, content_index: index,
-                                                  delta: JSON.generate(call.arguments))
+        built = +""
+        JSON.generate(call.arguments).scan(/.{1,#{@chunk_size}}/m) do |chunk|
+          built << chunk
+          emit_event(emit, :toolcall_delta, blocks + [in_progress(call, built)],
+                     content_index: index, delta: chunk)
+        end
         blocks << call
         emit_event(emit, :toolcall_end, blocks, content_index: index, tool_call: call)
       end
 
+      def in_progress(call, json)
+        parsed = PartialJson.parse(json)
+        ToolCall.new(id: call.id, name: call.name,
+                     arguments: parsed.is_a?(Hash) ? parsed : {})
+      end
+
       def finish(turn, blocks, emit)
         reason = turn[:stop_reason] ||
                  (blocks.any?(ToolCall) ? StopReason::TOOL_USE : StopReason::STOP)

data/lib/mistri/result.rb

@@ -12,8 +12,12 @@ module Mistri
   # output is a task's validated value, nil on plain runs. usage is the
   # run's own accounting: every persisted turn plus compaction calls, summed
   # (a resumed run counts from the resume; task sums across its fix passes).
-  Result = Data.define(:message, :status, :pending, :output, :usage) do
-    def initialize(message:, status:, pending: [], output: nil, usage: Usage.zero)
+  # handed_off marks a run that ended because an ends_turn tool executed:
+  # complete, but the final word was the tool's, and whatever comes next (a
+  # human's answer) arrives as the next run's input.
+  Result = Data.define(:message, :status, :pending, :output, :usage, :handed_off) do
+    def initialize(message:, status:, pending: [], output: nil, usage: Usage.zero,
+                   handed_off: false)
       super
     end
 
@@ -22,6 +26,7 @@ module Mistri
     def aborted? = status == :aborted
     def stopped_by_budget? = status == :budget
     def errored? = status == :error
+    def handed_off? = handed_off
 
     def text = message&.text
     def stop_reason = message&.stop_reason

data/lib/mistri/retry_policy.rb

@@ -4,8 +4,8 @@ module Mistri
   # When a failed turn is worth retrying, and how long to wait. Transient
   # failures (rate limits, overload, server errors, timeouts, dropped or
   # truncated streams) retry with jittered exponential backoff, honoring the
-  # provider's retry-after when it sent one. Everything else — auth, invalid
-  # requests, our own bugs — fails fast.
+  # provider's retry-after when it sent one. Everything else (auth, invalid
+  # requests, our own bugs) fails fast.
   #
   # attempts counts retries, not calls: attempts 3 means up to four requests.
   class RetryPolicy
@@ -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/session.rb

@@ -66,6 +66,11 @@ module Mistri
       entries.reverse_each.find { |entry| entry["type"] == "compaction" }
     end
 
+    # The inbox: entry types queued for the loop's next turn boundary, each
+    # mapped to the marker key its fold leaves on the consuming message
+    # entry.
+    INBOX = { "steer" => "steer_id", "subagent_report" => "report_id" }.freeze
+
     # Queue a message for a running exchange from any process. The loop folds
     # pending steers into the transcript at the next turn boundary, so the
     # model sees them mid-run; one that arrives as the model finishes cleanly
@@ -74,12 +79,64 @@ module Mistri
       append("steer", "id" => SecureRandom.uuid, "message" => Message.user(text).to_h)
     end
 
-    # Steers not yet folded into the transcript, oldest first. The folding
-    # message entry carries the steer id, so consumption is derived from the
-    # log alone and reads the same from every process.
+    # A sub-agent's report, queued for this session the way a steer is: it
+    # folds into the transcript at the next turn boundary as a labeled block
+    # the model can react to ("[Magpie finished] <report>"), while the typed
+    # entry keeps name, status, and the raw text for hosts to render as a
+    # report card rather than a fake user message. One report per child,
+    # ever: a duplicate delivery (a redelivered queue job, a lease race) is
+    # dropped, and the return says which happened. Reports normally arrive
+    # via SubAgent.run_dispatched; call this directly only from a custom
+    # dispatch path.
+    def deliver_report(name:, session_id:, status:, text: nil) # rubocop:disable Naming/PredicateMethod
+      already = entries.any? do |entry|
+        entry["type"] == "subagent_report" && entry["session_id"] == session_id
+      end
+      return false if already
+
+      append("subagent_report", "id" => SecureRandom.uuid, "name" => name,
+                                "session_id" => session_id, "status" => status, "report" => text,
+                                "message" => Message.user(report_label(name, status, text)).to_h)
+      true
+    end
+
+    # Everything queued for the loop's next turn boundary (steers and
+    # sub-agent reports), oldest first, in arrival order. The folding
+    # message entry carries the source entry's id under its marker key, so
+    # consumption is derived from the log alone and reads the same from
+    # every process. A host that wakes an idle session when a steer arrives
+    # should watch this instead: a report deserves the same pickup.
+    def pending_inbox
+      log = entries
+      folded = log.flat_map { |entry| entry.values_at(*INBOX.values) }.compact.to_set
+      log.select { |entry| INBOX.key?(entry["type"]) && !folded.include?(entry["id"]) }
+    end
+
+    # The steer-only slice of the inbox, oldest first.
     def pending_steers
-      folded = entries.filter_map { |entry| entry["steer_id"] }
-      entries.select { |entry| entry["type"] == "steer" && !folded.include?(entry["id"]) }
+      pending_inbox.select { |entry| entry["type"] == "steer" }
+    end
+
+    # Sub-agents this session has spawned, in spawn order: one Child window
+    # per link entry, each reading the child's own session. Derived from the
+    # log alone, like everything else here.
+    def children
+      entries.filter_map do |entry|
+        next unless entry["type"] == "subagent"
+
+        Child.new(name: entry["name"], session_id: entry["session_id"], store: @store)
+      end
+    end
+
+    # The session as a reader renders it: entries in order with inline image
+    # bytes stripped, and, with include_children, every sub-agent's own
+    # transcript spliced in after its link entry. Spliced entries carry an
+    # "origin" key shaped exactly like the live stream's event origins
+    # ("Magpie#ab12cd34", nesting joined with ">"), so a UI that rebuilds
+    # from this sees what it saw live, lanes included, running children's
+    # progress-so-far included. The raw log stays available as #entries.
+    def transcript(include_children: false)
+      splice(entries, include_children: include_children, prefix: nil, seen: Set[@id])
     end
 
     # Record a human's decision on a parked tool call. Decisions are session
@@ -137,6 +194,39 @@ module Mistri
       Message.user("#{Compaction::SUMMARY_PREFACE}\n\n#{summary}")
     end
 
+    # Each link entry opens its child's log in place, depth first, the way
+    # nested lanes opened live. The seen set makes expansion idempotent per
+    # child (a repeated or self-referencing link renders but never expands
+    # twice), so a hostile log cannot loop this.
+    def splice(log, include_children:, prefix:, seen:)
+      log.flat_map do |entry|
+        rendered = Child.strip_images(entry)
+        rendered = rendered.merge("origin" => prefix) if prefix
+        next [rendered] unless include_children && expandable?(entry, seen)
+
+        seen << entry["session_id"]
+        origin = "#{entry["name"]}##{entry["session_id"][0, 8]}"
+        origin = "#{prefix}>#{origin}" if prefix
+        child_log = self.class.new(store: @store, id: entry["session_id"]).entries
+        [rendered, *splice(child_log, include_children: true, prefix: origin, seen: seen)]
+      end
+    end
+
+    def expandable?(entry, seen)
+      entry["type"] == "subagent" && !seen.include?(entry["session_id"])
+    end
+
+    # How a report reads to the model: labeled with the worker's name and
+    # fate, so the parent knows exactly who finished and how.
+    def report_label(name, status, text)
+      case status
+      when "done" then "[#{name} finished] #{text}"
+      when "failed" then "[#{name} failed] #{text}"
+      when "stopped" then "[#{name} was stopped]"
+      else "[#{name} ended: #{status}]"
+      end
+    end
+
     def decide(call_id, approved:, note:)
       unless open_approvals.any? { |open| open[:call].id == call_id }
         raise ConfigurationError, "no open approval for #{call_id.inspect}"

data/lib/mistri/skill.rb

@@ -3,7 +3,7 @@
 module Mistri
   # One expert playbook: a name the model selects by, a description that
   # earns the selection, and the full body it reads before acting. Build
-  # them from anywhere — Skills.load reads a directory, and a host with
+  # them from anywhere: Skills.load reads a directory, and a host with
   # skills in a database constructs these directly.
   Skill = Data.define(:name, :description, :body) do
     def initialize(name:, description: "", body: "")

data/lib/mistri/skills.rb

@@ -3,7 +3,7 @@
 module Mistri
   # Loads skills and wires them into an agent: their one-line descriptions
   # ride the system prompt, and the model pulls a full body on demand with
-  # the read_skill tool — so a large library costs almost nothing until a
+  # the read_skill tool, so a large library costs almost nothing until a
   # skill is actually used.
   module Skills
     module_function