mistri 0.5.0 → 0.6.0

data/lib/mistri/budget.rb

@@ -16,11 +16,36 @@ module Mistri
 
     def none? = [@turns, @tokens, @cost_usd, @wall_clock].all?(&:nil?)
 
+    def cost? = !@cost_usd.nil?
+
+    def validate_provider!(provider)
+      return unless cost?
+      return if provider.respond_to?(:prices_usage?) && provider.prices_usage?
+
+      raise ConfigurationError,
+            "cost budget requires a catalogued model, list-priced origin, and deterministic " \
+            "standard service tier for #{provider.model.inspect}"
+    end
+
+    def validate_usage!(usage)
+      return unless cost?
+      return if usage.cost.known?
+
+      raise BudgetError.new(
+        "cost budget cannot continue after a request returned unpriced usage; not retrying",
+        usage:
+      )
+    end
+
     # The reason the run should stop, or nil to continue.
     def exceeded(turns:, usage:, elapsed: 0)
       return :turns if @turns && turns >= @turns
       return :tokens if @tokens && usage.total_tokens >= @tokens
-      return :cost if @cost_usd && usage.cost.total >= @cost_usd
+
+      if @cost_usd
+        validate_usage!(usage)
+        return :cost if usage.cost.total >= @cost_usd
+      end
       return :wall_clock if @wall_clock && elapsed >= @wall_clock
 
       nil

data/lib/mistri/child.rb

@@ -6,7 +6,7 @@ module Mistri
   # reads the same from any process, while the child runs and forever after.
   #
   #   session.children            # => [#<Mistri::Child Magpie done>, ...]
-  #   child.status                # => :running, :done, :stopped, :failed
+  #   child.status                # queued, running, interrupted, or terminal
   #   child.report                # the terminal entry's report, once finished
   #   child.transcript(tail: 20)  # recent entries, image bytes stripped
   #   child.say("Also check their pricing page")
@@ -20,8 +20,8 @@ module Mistri
     TERMINAL = "subagent_result"
     DISPATCHED = "subagent_dispatched"
     STARTED = "subagent_started"
-    # The states a worker can still be caught in: steerable, stoppable,
-    # worth waiting on.
+    # Work currently scheduled or queued, used for capacity and steering.
+    # Interrupted work is nonterminal but not actively live.
     LIVE = %i[running queued].freeze
 
     attr_reader :name, :session_id
@@ -30,10 +30,11 @@ module Mistri
 
     def self.stop_key(session_id) = "child-stop:#{session_id}"
 
-    def initialize(name:, session_id:, store:)
+    def initialize(name:, session_id:, store:, parent_session_id: nil)
       @name = name
       @session_id = session_id
       @store = store
+      @parent_session_id = parent_session_id
     end
 
     def status
@@ -49,10 +50,9 @@ module Mistri
       :running
     end
 
-    # A terminal entry exists: the child ended as done, stopped, or failed
-    # and will never run again. The question a queue retry asks; its
-    # inverse (started but no terminal) is what makes a crashed child
-    # re-runnable.
+    # A terminal entry exists: the child ended as done, stopped, or failed,
+    # so a later matching delivery must not run it again. The inverse
+    # (started but no terminal) is what makes a crashed child re-runnable.
     def finished?
       !terminal_entry.nil?
     end
@@ -82,17 +82,17 @@ module Mistri
       session.steer(text)
     end
 
-    # Ask a live child to stop, from any process. A running child's runner
-    # sees the flag within a tick and trips its own signal; a queued child
-    # is cancelled outright with a stopped terminal, which the runner
-    # honors by never starting it. Stop is cross-process by nature, so it
-    # needs a lock adapter; without one this returns false. An action that
-    # reports acceptance, not a predicate.
+    # Ask a child to stop, from any process. An inactive dispatched child is
+    # cancelled durably under its lease; an inline or already-running child
+    # receives the stop flag. Repeating stop on a stopped dispatched child
+    # reconciles a missing parent report. Stop is
+    # cross-process by nature, so it needs a lock adapter; without one this
+    # returns false. An action that reports acceptance, not a predicate.
     def stop # rubocop:disable Naming/PredicateMethod
       return false unless Mistri.locks
 
-      session.append(TERMINAL, "status" => "stopped") if status == :queued
-      Mistri.locks.set_flag(self.class.stop_key(@session_id))
+      outcome = cancel_inactive
+      Mistri.locks.set_flag(self.class.stop_key(@session_id)) if outcome == :contended
       true
     end
 
@@ -119,6 +119,62 @@ module Mistri
 
     private
 
+    # Cancellation and a runner compete for the same lease. Acquiring it
+    # proves no unexpired lease is present, so ordinary inactive dispatched
+    # work can end here; a stale holder may still resume under the documented
+    # tokenless lease trade-off. Status cannot be rechecked because our own
+    # lease would read running.
+    def cancel_inactive
+      key = self.class.lease_key(@session_id)
+      lease = Locks.hold(key)
+      return :contended unless lease
+
+      begin
+        log = session.entries
+        terminal = log.reverse_each.find { |entry| entry["type"] == TERMINAL }
+        dispatched = log.any? { |entry| entry["type"] == DISPATCHED }
+        if terminal
+          deliver_cancellation if terminal["status"] == "stopped"
+          :finished
+        elsif dispatched
+          session.append(TERMINAL, "status" => "stopped")
+          deliver_cancellation
+          :cancelled
+        else
+          Mistri.locks.set_flag(self.class.stop_key(@session_id))
+          :signaled
+        end
+      ensure
+        lease.release
+      end
+    end
+
+    # A cancelled queue item may never be delivered, so the lease owner
+    # must route its durable outcome. Current versions trust only the stored
+    # grant; legacy children fall back to the parent link because their
+    # dispatched entry did not retain a spec.
+    def deliver_cancellation
+      dispatched = session.entries.find { |entry| entry["type"] == DISPATCHED }
+      return unless dispatched
+
+      spec = dispatched["spec"]
+      parent_id, label = cancellation_route(spec)
+      return unless parent_id.is_a?(String) && !parent_id.empty?
+      return unless label.is_a?(String) && !label.empty?
+
+      Session.new(store: @store, id: parent_id)
+             .deliver_report(name: label, session_id: @session_id, status: "stopped")
+    end
+
+    def cancellation_route(spec)
+      return [@parent_session_id, @name] if spec.nil?
+      return [nil, nil] unless spec.is_a?(Hash)
+      return [nil, nil] unless spec["spec_version"] == SubAgent::DISPATCH_SPEC_VERSION
+      return [nil, nil] unless spec["session_id"] == @session_id
+
+      [spec["parent_session_id"], spec["name"]]
+    end
+
     def session
       @session ||= Session.new(store: @store, id: @session_id)
     end

data/lib/mistri/compaction.rb

@@ -14,6 +14,7 @@ module Mistri
   class Compaction
     DEFAULT_RESERVE = 16_384
     DEFAULT_KEEP_RECENT = 20_000
+    OUTPUT_SAFETY = 4_096
     IMAGE_CHARS = 4_800
 
     SUMMARY_PREFACE = "The earlier conversation was compacted. This summary replaces it:"
@@ -21,28 +22,43 @@ module Mistri
     attr_reader :reserve, :keep_recent, :window, :instructions
 
     # window overrides the model catalog's context window (required for
-    # models the catalog does not know). instructions add a host-specific
-    # focus to the summary prompt.
-    def initialize(reserve: DEFAULT_RESERVE, keep_recent: DEFAULT_KEEP_RECENT,
+    # models the catalog does not know). A nil reserve selects automatic
+    # headroom; a number is explicit host policy. instructions add a
+    # host-specific focus to the summary prompt.
+    def initialize(reserve: nil, keep_recent: DEFAULT_KEEP_RECENT,
                    window: nil, instructions: nil)
-      @reserve = reserve
+      @automatic_reserve = reserve.nil?
+      @reserve = reserve || DEFAULT_RESERVE
       @keep_recent = keep_recent
       @window = window
       @instructions = instructions
     end
 
-    # Compact when the context has grown into the reserve headroom. An
-    # unknown window never triggers.
-    def needed?(tokens, window)
-      window ? tokens > window - reserve : false
+    def automatic_reserve? = @automatic_reserve
+
+    # Automatic headroom fits output that shares the context window, plus
+    # estimation and framing slack. An explicit reserve remains host policy.
+    # An unknown window never triggers.
+    def needed?(tokens, window, max_output: nil)
+      window ? tokens > window - effective_reserve(max_output) : false
+    end
+
+    private
+
+    def effective_reserve(max_output)
+      return reserve unless automatic_reserve?
+
+      max_output ? [max_output + OUTPUT_SAFETY, reserve].max : reserve
     end
 
     class << self
       # Context size for a replay: the last healthy turn's reported tokens
       # (prompt, cache, and output all sit in context next turn) plus an
       # estimate of every message after it.
-      def context_tokens(messages)
-        index = messages.rindex { |message| reported(message) }
+      def context_tokens(messages, usage_from: 0)
+        index = (usage_from...messages.length).reverse_each.find do |position|
+          reported(messages[position])
+        end
         base = index ? reported(messages[index]) : 0
         messages.drop(index ? index + 1 : 0).sum(base) { |message| estimate(message) }
       end

data/lib/mistri/compactor.rb

@@ -9,10 +9,12 @@ module Mistri
   # transcript UIs; only what the model sees shrinks. Callable from any
   # process (a UI button, a job), with or without a running agent.
   #
-  # Cuts land only on user messages, so a tool call and its result always
-  # stay on the same side, and a parked approval's turn is never cut away
-  # from the resume that must answer it.
+  # Cuts land on user messages or assistant tool-call turns, never results,
+  # so every call/result set stays on one side. A parked approval's turn is
+  # never cut away from the resume that must answer it.
   class Compactor
+    TOOL_RESULT_MAX_CHARS = 2_000
+
     SUMMARIZER_SYSTEM = <<~PROMPT
       You are a context summarization assistant. Read the conversation and
       produce only the structured summary you are asked for. Do not continue
@@ -43,8 +45,8 @@ module Mistri
       ## Critical Context
       - [Data, names, or references needed to continue, or "(none)"]
 
-      Keep each section concise. Preserve exact identifiers, names, and error
-      messages.
+      Keep each section concise. Preserve exact identifiers, names, paths,
+      URLs, commands, numbers, and error messages.
     FORMAT
 
     CHECKPOINT_PROMPT = <<~PROMPT.freeze
@@ -82,7 +84,7 @@ module Mistri
         return nil if head.empty?
 
         emit&.call(Event.new(type: :compacting))
-        tokens_before = Compaction.context_tokens(replay.map(&:first))
+        tokens_before = session.context_tokens
         reply = summarize(provider, head, previous, settings.instructions)
         session.append("compaction", "summary" => reply.text,
                                      "kept_from" => cut, "tokens_before" => tokens_before)
@@ -95,7 +97,9 @@ module Mistri
         boundary = keep_boundary(replay, settings.keep_recent)
         return nil unless boundary
 
-        candidates = replay.filter_map { |(message, index)| index if index && message.user? }
+        candidates = replay.filter_map do |message, index|
+          index if index && cut_candidate?(message)
+        end
         cut = candidates.find { |index| index >= boundary } || candidates.last
         cut = clamp_to_open_approvals(cut, session)
         return nil unless cut
@@ -104,8 +108,12 @@ module Mistri
         first && cut > first ? cut : nil
       end
 
+      def cut_candidate?(message)
+        message.user? || (message.assistant? && message.tool_calls?)
+      end
+
       # Walk back from the tail until the keep budget is spent; the cut then
-      # snaps forward to a user message, so replay keeps at most about
+      # snaps to the next safe turn boundary, so replay keeps at most about
       # keep_recent tokens of recent turns.
       def keep_boundary(replay, keep_recent)
         kept = 0
@@ -145,7 +153,10 @@ module Mistri
         prompt << (previous ? UPDATE_PROMPT : CHECKPOINT_PROMPT)
         prompt << "\nAdditional focus: #{instructions}\n" if instructions
         reply = provider.stream(messages: [Message.user(prompt)], system: SUMMARIZER_SYSTEM)
-        raise CompactionError, "summarization failed: #{reply.error_message}" unless usable?(reply)
+        unless usable?(reply)
+          raise CompactionError.new("summarization failed: #{reply.error_message}",
+                                    usage: reply.usage)
+        end
 
         reply
       end
@@ -155,7 +166,7 @@ module Mistri
       end
 
       def finish(session, reply, tokens_before, &emit)
-        tokens_after = Compaction.context_tokens(session.messages)
+        tokens_after = session.context_tokens
         emit&.call(Event.new(type: :compaction, content: reply.text))
         { summary: reply.text, tokens_before: tokens_before,
           tokens_after: tokens_after, usage: reply.usage }
@@ -169,13 +180,25 @@ module Mistri
       end
 
       def text_of(message)
-        message.content.filter_map do |block|
+        text = message.content.filter_map do |block|
           case block
           when Content::Text then block.text
           when Content::Image then "[image]"
           when ToolCall then "[called #{block.name} with #{JSON.generate(block.arguments)}]"
           end
         end.join("\n")
+        message.tool? ? truncate_tool_result(text) : text
+      end
+
+      # Large tool output remains durable and unchanged on ordinary model
+      # requests; only the lossy summary wire is bounded, with both ends kept.
+      def truncate_tool_result(text)
+        return text if text.length <= TOOL_RESULT_MAX_CHARS
+
+        marker = "\n[tool result truncated; original length: #{text.length} characters]\n"
+        visible = TOOL_RESULT_MAX_CHARS - marker.length
+        head = (visible * 0.75).floor
+        "#{text[0, head]}#{marker}#{text[-(visible - head), visible - head]}"
       end
     end
   end

data/lib/mistri/console.rb

@@ -98,15 +98,24 @@ module Mistri
         next Console.unknown(context.session, args["agent"]) unless child
 
         status = child.status
-        if !Child::LIVE.include?(status)
+        if status == :stopped
+          child.stop
+          "#{child.name} is already stopped."
+        elsif !Child::LIVE.include?(status) && status != :interrupted
           "#{child.name} is already #{status}."
         elsif !child.stop
           "Stopping needs a lock adapter (Mistri.locks) and none is configured."
-        elsif status == :queued
-          "Cancelled. #{child.name} had not started and never will."
         else
-          "Stop requested. #{child.name} halts within a second or two; " \
-            "its partial work stays readable through read_agent."
+          stopped = child.status
+          if stopped == :stopped
+            "Cancelled. #{child.name} is marked stopped; ordinary queue delivery " \
+              "will not run it again."
+          elsif %i[done failed].include?(stopped)
+            "#{child.name} finished as #{stopped} before the stop took effect."
+          else
+            "Stop requested. #{child.name}'s runner receives the request promptly " \
+              "and stops at a cooperative boundary; partial work stays readable."
+          end
         end
       end
     end
@@ -133,7 +142,8 @@ module Mistri
     # promptly, never held hostage to the timeout.
     def await(child, timeout, poll, signal = nil)
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
-      while Child::LIVE.include?(status = child.status)
+      until child.finished?
+        status = child.status
         return "The wait was stopped; #{child.name} is still #{status}." if signal&.aborted?
 
         if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
@@ -172,13 +182,24 @@ module Mistri
       calls = blocks.filter_map do |block|
         next unless block.is_a?(Hash) && block["type"] == "tool_call"
 
-        "#{block["name"]}(#{JSON.generate(block["arguments"] || {})[0, 80]})"
+        "#{block["name"]}(#{Console.render_arguments(block)})"
       end
       text = Console.text_of(message["content"])
       parts = [text[0, 240], *calls].reject { |part| part.to_s.empty? }
       "#{message["role"]}: #{parts.join(" | ")}" unless parts.empty?
     end
 
+    def render_arguments(block)
+      if block["arguments_error"]
+        details = { "arguments_error" => block["arguments_error"] }
+        details = { "arguments" => block["arguments"] }.merge(details) if block.key?("arguments")
+        return JSON.generate(details)[0, 80]
+      end
+
+      arguments = block.key?("arguments") ? block["arguments"] : {}
+      JSON.generate(arguments)[0, 80]
+    end
+
     def text_of(content)
       return content.to_s unless content.is_a?(Array)
 

data/lib/mistri/content.rb

@@ -17,7 +17,10 @@ module Mistri
     # `signature` carries opaque provider metadata that must round-trip, such as
     # the OpenAI Responses message id and output phase.
     Text = Data.define(:text, :signature) do
-      def initialize(text:, signature: nil) = super(text: Content.freeze_string(text), signature:)
+      def initialize(text:, signature: nil)
+        signature = Content.freeze_string(signature) if signature.is_a?(String)
+        super(text: Content.freeze_string(text), signature:)
+      end
 
       def type = :text
 
@@ -29,6 +32,7 @@ module Mistri
     # filter hid, leaving only the signature.
     Thinking = Data.define(:thinking, :signature, :redacted) do
       def initialize(thinking:, signature: nil, redacted: false)
+        signature = Content.freeze_string(signature) if signature.is_a?(String)
         super(thinking: Content.freeze_string(thinking), signature:, redacted:)
       end
 
@@ -89,8 +93,10 @@ module Mistri
                      redacted: h.fetch("redacted", false))
       when "image" then Image.new(data: h["data"], mime_type: h["mime_type"])
       when "tool_call"
-        ToolCall.new(id: h["id"], name: h["name"], arguments: h["arguments"] || {},
-                     signature: h["signature"])
+        arguments = h.key?("arguments") ? h["arguments"] : {}
+        ToolCall.new(id: h["id"], name: h["name"], arguments:,
+                     signature: h["signature"], arguments_error: h["arguments_error"],
+                     provider_call_id: h["provider_call_id"])
       else raise ArgumentError, "unknown content block type #{h["type"].inspect}"
       end
     end

data/lib/mistri/dispatchers.rb

@@ -2,10 +2,9 @@
 
 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.
+  # 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
@@ -13,10 +12,12 @@ module Mistri
   #
   #   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).
+  # 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
@@ -34,11 +35,12 @@ module Mistri
         ::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.
+          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: " \
-               "#{e.class}: #{e.message}"
+               "#{reported.class}: #{reported.message}"
         end
         nil
       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 }