mistri 0.4.1 → 0.6.0

data/lib/mistri/dispatchers.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Mistri
+  # How a background child actually executes. The spawn tool hands every
+  # dispatcher two things: a versioned serializable spec (name, session_id,
+  # parent_session_id, type, instructions, tool_names, model, task) and a
+  # runner closure that invokes the host runtime factory inside this process.
+  #
+  # 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 invokes the host factory inside the worker and keeps the
+  # spawn-time event sink. In-process children stream to whoever watched the
+  # spawn; that sink must outlive the parent's turn (a broadcast lambda does,
+  # a request-scoped object may not) and hears from the worker's thread,
+  # concurrently with the parent's own events. The gem's sinks tolerate that;
+  # a custom one must too.
+  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
+          reported = EventDelivery.original(e)
+          # Execution failures have a durable terminal before re-raising;
+          # cleanup may raise after a successful terminal. Neither should
+          # make a thread die loudly or disappear without a diagnostic.
+          warn "mistri: background runner for #{spec["name"].inspect} crashed: " \
+               "#{reported.class}: #{reported.message}"
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/mistri/errors.rb

@@ -11,6 +11,10 @@ module Mistri
   # Missing or contradictory setup: an unknown model, an absent API key.
   class ConfigurationError < Error; end
 
+  # A queue payload is not the grant persisted for its child. The unchanged
+  # delivery is poison: discard and alert instead of retrying it.
+  class DispatchGrantError < ConfigurationError; end
+
   # A provider request failed. Carries the HTTP status and response body when
   # the transport got that far.
   class ProviderError < Error
@@ -57,20 +61,89 @@ module Mistri
     def self.default_message = "provider server error"
   end
 
+  # An inbound body or protocol record crossed its configured byte boundary.
+  class ResponseTooLargeError < Error
+    attr_reader :kind, :limit
+
+    def initialize(kind:, limit:)
+      @kind = kind
+      @limit = limit
+      label = kind.to_s.tr("_", " ")
+      super("#{label} exceeded the byte limit (#{limit} bytes)")
+    end
+  end
+
+  # A JSON protocol record crossed a structural boundary before parsing.
+  class ResponseTooComplexError < Error
+    attr_reader :kind, :limit
+
+    def initialize(kind:, limit:)
+      @kind = kind
+      @limit = limit
+      label = kind.to_s.tr("_", " ")
+      super("#{label} exceeded the complexity limit (#{limit})")
+    end
+  end
+
+  # A non-replayable request has no confirmed response, so execution is unknown.
+  class AmbiguousDeliveryError < ProviderError
+    def self.default_message
+      "connection failed before the response was confirmed; the operation may have completed; " \
+        "do not retry automatically; verify external state first"
+    end
+  end
+
+  # The provider rejected the request itself: an invalid prompt, a bad
+  # image, a policy violation. Never retried; the same input cannot succeed.
+  class InvalidRequestError < ProviderError
+    def self.default_message = "provider rejected the request"
+  end
+
   # Tool arguments or structured output that violate their declared schema.
   class SchemaError < Error; end
 
   # A run cancelled by the host, raised only when the caller opts into raising.
   class AbortError < Error; end
 
-  # A run stopped by its turn, token, cost, or wall-clock budget.
-  class BudgetError < Error; end
+  # A cost-budgeted request returned without trustworthy accounting. Usage and
+  # provider_message preserve the uncertain attempt for host reconciliation.
+  class BudgetError < Error
+    attr_reader :usage, :provider_message
+
+    def initialize(message = nil, usage: nil, provider_message: nil)
+      @usage = usage
+      @provider_message = provider_message
+      super(message)
+    end
+  end
 
   # A text edit that did not match uniquely, or overlapped another edit.
   class EditError < Error; end
 
-  # Compaction could not produce a usable summary.
-  class CompactionError < Error; end
+  # A conditional document write lost to a different committed version. The
+  # revisions stay off the message so a stale full replacement cannot borrow
+  # a fresh token without reading the matching content.
+  class WorkspaceConflictError < Error
+    attr_reader :path, :expected_revision, :actual_revision
+
+    def initialize(path, expected_revision: nil, actual_revision: nil)
+      @path = path.to_s.dup.freeze
+      @expected_revision = expected_revision.nil? ? nil : expected_revision.to_s.dup.freeze
+      @actual_revision = actual_revision.nil? ? nil : actual_revision.to_s.dup.freeze
+      super("document #{@path.inspect} changed; read it again before retrying")
+    end
+  end
+
+  # Compaction could not produce a usable summary. Usage preserves any billed
+  # provider attempt even though no checkpoint was written.
+  class CompactionError < Error
+    attr_reader :usage
+
+    def initialize(message = nil, usage: nil)
+      @usage = usage
+      super(message)
+    end
+  end
 
   # The machine-readable shape of a stream failure, carried on errored
   # assistant messages so retry policies and hosts can classify without
@@ -84,6 +157,12 @@ module Mistri
       when RateLimitError
         { "type" => "RateLimitError", "status" => reason.status,
           "retry_after" => reason.retry_after }.compact
+      when ResponseTooLargeError
+        { "type" => "ResponseTooLargeError", "kind" => reason.kind.to_s,
+          "limit" => reason.limit }
+      when ResponseTooComplexError
+        { "type" => "ResponseTooComplexError", "kind" => reason.kind.to_s,
+          "limit" => reason.limit }
       when ProviderError
         { "type" => reason.class.name.split("::").last, "status" => reason.status }.compact
       when Exception then { "type" => reason.class.name }

data/lib/mistri/event.rb

@@ -11,34 +11,54 @@ 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)
+                            :duration, :attempt, :max_attempts, :delay,
+                            :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
     # 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
       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
     ].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, attempt: nil, max_attempts: nil, delay: nil)
+                   duration: nil, attempt: nil, max_attempts: nil, delay: 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
 
@@ -46,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: }.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/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 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 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
+  # :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

@@ -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)