mistri 0.4.1 → 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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Mistri
+  # A sub-agent as its parent (or the host UI) sees it: a window onto the
+  # child's own session. Everything here is derived from the store, so it
+  # reads the same from any process, while the child runs and forever after.
+  #
+  #   session.children            # => [#<Mistri::Child Magpie done>, ...]
+  #   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")
+  #
+  # Status is a walk over the child's own entries: a terminal entry wins; a
+  # started child is :running while its lease holds and :interrupted once
+  # it lapses (with a lock adapter; without one there is no liveness signal
+  # and no-terminal stays :running); a dispatched-but-never-started child is
+  # :queued, honestly, because the host's queue owns that gap.
+  class Child
+    TERMINAL = "subagent_result"
+    DISPATCHED = "subagent_dispatched"
+    STARTED = "subagent_started"
+    # 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
+
+    def self.lease_key(session_id) = "child:#{session_id}"
+
+    def self.stop_key(session_id) = "child-stop:#{session_id}"
+
+    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
+      log = session.entries
+      terminal = log.reverse_each.find { |entry| entry["type"] == TERMINAL }
+      return terminal["status"].to_sym if terminal
+      if log.any? { |entry| entry["type"] == DISPATCHED } &&
+         log.none? { |entry| entry["type"] == STARTED }
+        return :queued
+      end
+      return :interrupted if Mistri.locks && !Mistri.locks.held?(self.class.lease_key(@session_id))
+
+      :running
+    end
+
+    # 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
+
+    def report
+      terminal_entry&.fetch("report", nil)
+    end
+
+    # The terminal entry's error string, once failed.
+    def error
+      terminal_entry&.fetch("error", nil)
+    end
+
+    # Recent entries, oldest first, with inline image bytes replaced by a
+    # marker: transcripts are for reading and re-sending, not for hauling
+    # screenshots back into a context window.
+    def transcript(tail: 20)
+      entries = session.entries
+      entries = entries.last(tail) if tail
+      entries.map { |entry| self.class.strip_images(entry) }
+    end
+
+    # Queue a message the child folds at its next turn boundary. Delivery is
+    # honest, not instant: a child mid-step sees it after that step, and a
+    # child that finishes first never sees it.
+    def say(text)
+      session.steer(text)
+    end
+
+    # 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
+
+      outcome = cancel_inactive
+      Mistri.locks.set_flag(self.class.stop_key(@session_id)) if outcome == :contended
+      true
+    end
+
+    def to_h
+      { "name" => name, "session_id" => session_id, "status" => status.to_s }
+    end
+
+    def inspect
+      "#<Mistri::Child #{name} #{status}>"
+    end
+
+    def self.strip_images(value)
+      case value
+      when Hash
+        if value["data"] && value["mime_type"]
+          value.except("data").merge("omitted" => true)
+        else
+          value.transform_values { |nested| strip_images(nested) }
+        end
+      when Array then value.map { |nested| strip_images(nested) }
+      else value
+      end
+    end
+
+    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
+
+    def terminal_entry
+      session.entries.reverse_each.find { |entry| entry["type"] == TERMINAL }
+    end
+  end
+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

@@ -5,14 +5,16 @@ require "json"
 module Mistri
   # Compacts a session in place: everything before a cut point is summarized
   # by the provider, and a compaction entry redirects replay to the summary
-  # plus the kept tail. Append-only — the full history stays in the store for
+  # plus the kept tail. Append-only: the full history stays in the store for
   # 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

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Mistri
+  # The management console: the tools an agent gets for managing the workers
+  # it spawns. Every tool is a thin wrapper over Session#children and the
+  # Child facade, the same functions a host UI calls, so nothing the agent
+  # can do is hidden from the user and nothing the user does confuses the
+  # agent. Tools are stateless: each call reads the calling session's
+  # children at that moment.
+  #
+  #   agent = Mistri::Agent.new(provider:, tools: [spawn, *Mistri::Console.tools])
+  #
+  # Workers are addressed by name or session id, uniformly, in every tool.
+  # When two workers share a name, the most recently spawned one answers;
+  # ids stay unambiguous.
+  module Console
+    READ_TIMEOUT = 300
+    POLL = 0.5
+
+    module_function
+
+    def tools(read_timeout: READ_TIMEOUT, poll: POLL)
+      [list_agents, read_agent(timeout: read_timeout, poll: poll), steer_agent, stop_agent]
+    end
+
+    def list_agents
+      Tool.define(
+        "list_agents",
+        "See your workers: who is running, who finished, who was stopped. " \
+        "Check here before spawning a duplicate."
+      ) do |_args, context|
+        children = context.session.children
+        next "You have no workers." if children.empty?
+
+        children.map do |child|
+          "#{child.name} (#{child.session_id[0, 8]}): #{child.status}"
+        end.join("\n")
+      end
+    end
+
+    def read_agent(timeout: READ_TIMEOUT, poll: POLL)
+      Tool.define(
+        "read_agent",
+        "Read what a worker has done so far without interrupting it, or pass " \
+        "wait to block until it finishes and get its report.",
+        schema: lambda {
+          string :agent, "The worker's name or session id", required: true
+          integer :tail, "How many recent entries to read (default 20)"
+          boolean :wait, "Block until the worker finishes, then return its report"
+        }
+      ) do |args, context|
+        child = Console.find(context.session, args["agent"])
+        next Console.unknown(context.session, args["agent"]) unless child
+
+        if args["wait"]
+          Console.await(child, timeout, poll, context.signal)
+        else
+          Console.render(child, args.fetch("tail", 20).to_i.clamp(1, 200))
+        end
+      end
+    end
+
+    def steer_agent
+      Tool.define(
+        "steer_agent",
+        "Redirect or correct a running worker. It sees your message at its " \
+        "next step; it may finish first. For a full restart, stop it and " \
+        "spawn again with better instructions.",
+        schema: lambda {
+          string :agent, "The worker's name or session id", required: true
+          string :message, "What the worker should know or do differently", required: true
+        }
+      ) do |args, context|
+        child = Console.find(context.session, args["agent"])
+        next Console.unknown(context.session, args["agent"]) unless child
+
+        status = child.status
+        if Child::LIVE.include?(status)
+          child.say(args.fetch("message"))
+          "Queued. #{child.name} sees it at its next step; it may finish first."
+        else
+          "#{child.name} is #{status}, so there is nothing to steer. " \
+            "Spawn a new worker for follow-up work."
+        end
+      end
+    end
+
+    def stop_agent
+      Tool.define(
+        "stop_agent",
+        "Stop one worker. Its partial work is kept and its transcript stays " \
+        "readable. Other workers and your own run continue.",
+        schema: lambda {
+          string :agent, "The worker's name or session id", required: true
+        }
+      ) do |args, context|
+        child = Console.find(context.session, args["agent"])
+        next Console.unknown(context.session, args["agent"]) unless child
+
+        status = child.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."
+        else
+          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
+
+    # Ids are advertised as unambiguous, so they resolve first: exact, then
+    # an 8+ character prefix (what list_agents displays). Names come last,
+    # latest spawn winning on duplicates, so a model-chosen name can never
+    # shadow another worker's id.
+    def find(session, ref)
+      children = session.children
+      children.find { |child| child.session_id == ref } ||
+        (ref.to_s.length >= 8 &&
+          children.find { |child| child.session_id.start_with?(ref) }) ||
+        children.reverse_each.find { |child| child.name == ref }
+    end
+
+    def unknown(session, ref)
+      names = session.children.map(&:name).uniq
+      known = names.empty? ? "you have no workers" : "your workers: #{names.join(", ")}"
+      "No worker matches #{ref.inspect}; #{known}."
+    end
+
+    # The wait is cooperative like everything else: the run's abort ends it
+    # promptly, never held hostage to the timeout.
+    def await(child, timeout, poll, signal = nil)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      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
+          return "#{child.name} is still #{status} after #{timeout.round}s. " \
+                 "Read it without wait to see progress, or stop it."
+        end
+        sleep poll
+      end
+      report = child.report
+      "#{child.name} #{child.status}." + (report ? "\n#{report}" : "")
+    end
+
+    # A compact, readable transcript for a model: one line per entry, text
+    # extracted, long values truncated. The gem never summarizes; the
+    # caller can.
+    def render(child, tail)
+      entries = child.transcript(tail: tail)
+      return "#{child.name} (#{child.status}): no entries yet." if entries.empty?
+
+      lines = entries.map { |entry| Console.line(entry) }.compact
+      "#{child.name} (#{child.status}), last #{lines.length} entries:\n#{lines.join("\n")}"
+    end
+
+    def line(entry)
+      case entry["type"]
+      when "message" then message_line(entry["message"] || {})
+      when Child::TERMINAL
+        ["#{entry["status"]}:", entry["report"] || entry["error"]].compact.join(" ")[0, 300]
+      end
+    end
+
+    # Tool calls ride the message's content as typed blocks, never as a
+    # separate key; render both channels from the blocks.
+    def message_line(message)
+      blocks = message["content"].is_a?(Array) ? message["content"] : []
+      calls = blocks.filter_map do |block|
+        next unless block.is_a?(Hash) && block["type"] == "tool_call"
+
+        "#{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)
+
+      content.filter_map { |block| block["text"] if block.is_a?(Hash) }.join(" ")
+    end
+  end
+end

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