mistri 0.4.0 → 0.5.0

data/lib/mistri/agent.rb

@@ -13,8 +13,12 @@ module Mistri
   # marked needs_approval suspends the run instead of executing: the run
   # returns at once (no thread ever waits on a human), the decision arrives
   # later as a session entry from any process, and resume settles it and
-  # carries on. Session#steer queues a user message from any process while
-  # the loop runs; it folds into the transcript at the next turn boundary.
+  # carries on. A tool marked ends_turn ends the run once it executes: the
+  # model does not get another word, and whatever comes next (a human's
+  # answer to ask_user, say) arrives as the next run's input. Session#steer
+  # queues a user message from any process while the loop runs; it folds
+  # into the transcript at the next turn boundary, and a background child's
+  # report arrives through the same inbox.
   class Agent
     # compaction defaults on so long sessions survive their context window;
     # pass false to disable, or a tuned Compaction. It only ever triggers
@@ -52,12 +56,6 @@ module Mistri
 
     attr_reader :session
 
-    # What retries see when a completion answers nothing at all.
-    EMPTY_COMPLETION_ERROR = {
-      "type" => "EmptyCompletion",
-      "message" => "the provider returned an empty completion"
-    }.freeze
-
     # Run one exchange: append the user turn, then loop until the model
     # answers without tools, a gated tool suspends the run, the run aborts,
     # or a budget stops it.
@@ -66,13 +64,15 @@ module Mistri
     # on top; run alone does not validate.
     def run(input, images: [], signal: nil, output_schema: nil, &emit)
       if @session.open_approvals.any?
-        raise ConfigurationError, "session is awaiting approval decisions; call resume"
+        raise ConfigurationError,
+              "session is awaiting approvals; call resume"
       end
       if input.to_s.empty? && Array(images).empty?
-        raise ArgumentError, "run needs input text or images"
+        raise ArgumentError,
+              "run needs input text or images"
       end
 
-      fold_steers # steers queued while idle arrived first; keep that order
+      fold_inbox # anything queued while this session sat idle arrived first; keep that order
       @session.append_message(Message.user_with_images(input, images))
       loop_turns(signal, output_schema, &emit)
     end
@@ -80,7 +80,8 @@ module Mistri
     # Continue a suspended run. Undecided approvals return immediately, still
     # suspended. Decided ones settle first: approved calls execute, denied
     # calls answer in band so the model knows and can react. Then the loop
-    # carries on as if it never stopped.
+    # carries on as if it never stopped, unless a settled call's tool ends
+    # the turn, in which case its execution was the run's last word.
     def resume(signal: nil, &emit)
       open = @session.open_approvals
       pending = open.select { |approval| approval[:decision].nil? }
@@ -90,7 +91,12 @@ module Mistri
                           usage: Usage.zero)
       end
 
-      settle(open, signal, &emit)
+      executed = settle(open, signal, &emit)
+      if executed.any? { |call| ends_turn?(call) }
+        last = @session.messages.reverse_each.find(&:assistant?)
+        return finished(last, Usage.zero, signal, handed_off: true)
+      end
+
       loop_turns(signal, nil, &emit)
     end
 
@@ -102,21 +108,24 @@ module Mistri
     #
     # A run that suspends for approval returns as-is: validation applies to
     # completed runs only, so resume the session and re-ask if that happens
-    # mid-task.
+    # mid-task. A run an ends_turn tool ended returns as-is too: the floor
+    # belongs to whoever answers, and re-prompting for JSON would steal it
+    # back. Ask again once the answer arrives.
     def task(input, schema:, images: [], signal: nil, fixes: 1, &emit)
-      result = run(task_input(input, schema), images: images, signal: signal,
-                                              output_schema: schema, &emit)
+      result = run(TaskOutput.prompt(input, schema), images: images, signal: signal,
+                                                     output_schema: schema, &emit)
       spent = result.usage
       fixes.downto(0) do |remaining|
         result = result.with(usage: spent)
         return result unless result.completed?
+        return result if result.handed_off?
 
-        value = parse_output(result.text)
-        errors = task_errors(value, schema)
+        value = TaskOutput.parse(result.text)
+        errors = TaskOutput.errors(value, schema)
         return result.with(output: value) if errors.empty?
         raise SchemaError, "task output failed validation: #{errors.join("; ")}" if remaining.zero?
 
-        result = run(fix_prompt(errors), signal: signal, output_schema: schema, &emit)
+        result = run(TaskOutput.fix_prompt(errors), signal: signal, output_schema: schema, &emit)
         spent += result.usage
       end
     end
@@ -148,7 +157,7 @@ module Mistri
         reason = @budget.exceeded(turns: turns, usage: usage, elapsed: monotonic_now - started)
         return stop_for_budget(reason, usage, &emit) if reason
 
-        fold_steers
+        fold_inbox
         compacted = auto_compact(&emit)
         usage += compacted[:usage] if compacted&.dig(:usage)
         last = run_turn(signal, output_schema, &emit)
@@ -157,20 +166,21 @@ module Mistri
 
         # Any tool call the turn made must be answered or parked, or the
         # transcript is unpairable and replay fails.
-        parked = last.tool_calls? ? run_tools(last, signal, &emit) : []
+        parked, ended = last.tool_calls? ? run_tools(last, signal, &emit) : [[], false]
         return suspended(last, parked, usage) if parked.any?
-        return finished(last, usage) if done?(last, signal)
+        return finished(last, usage, signal, handed_off: ended) if ended || done?(last, signal)
       end
     end
 
-    # A steer that lands while the model finishes cleanly extends the run one
-    # more turn so it gets answered. Aborts, errors, and length stops always
-    # end the run; the steer stays pending for the next one.
+    # A steer or a child's report that lands while the model finishes
+    # cleanly extends the run one more turn, so it is answered rather than
+    # left dangling. Aborts, errors, and length stops always end the run;
+    # the inbox stays pending for the next one.
     def done?(last, signal)
       return false if last.stop_reason == StopReason::TOOL_USE && !signal&.aborted?
       return true if signal&.aborted? || last.stop_reason != StopReason::STOP
 
-      @session.pending_steers.empty?
+      @session.pending_inbox.empty?
     end
 
     # Compact when the context has grown into the reserve. A failed
@@ -191,13 +201,15 @@ module Mistri
       @compaction&.window || Models.find(@provider.model)&.context_window
     end
 
-    # Materialize queued steers into the transcript in arrival order. The
-    # folded message entry carries the steer id, which is what marks the steer
-    # consumed: one append is both the fold and the marker, so a crash between
-    # steers never double-delivers.
-    def fold_steers
-      @session.pending_steers.each do |steer|
-        @session.append("message", "message" => steer["message"], "steer_id" => steer["id"])
+    # Materialize the inbox, queued steers and sub-agent reports alike, into
+    # the transcript in arrival order. The folded message entry carries the
+    # source entry's id under its marker key, which is what marks the entry
+    # consumed: one append is both the fold and the marker, so a crash
+    # between folds never double-delivers.
+    def fold_inbox
+      @session.pending_inbox.each do |entry|
+        marker = Session::INBOX.fetch(entry["type"])
+        @session.append("message", "message" => entry["message"], marker => entry["id"])
       end
     end
 
@@ -208,44 +220,35 @@ module Mistri
     # the request.
     #
     # A transient failure retries the same request with backoff; the failed
-    # attempt is recorded as a retry entry, never as a message, so retries
-    # stay invisible to the model. Only the final outcome persists.
+    # attempt records as a retry entry, never as a message, and its terminal
+    # (:done or :error) holds at a gate, so retries stay invisible to the
+    # model and a recovered retry never shows the subscriber an error it
+    # walks back. Only the accepted attempt persists and terminates.
     def run_turn(signal, output_schema = nil, &emit)
       history = @transform_context.reduce(@session.messages) do |messages, transform|
         transform.call(messages)
       end
       attempt = 0
       loop do
+        held = nil
+        gate = emit && ->(event) { event.terminal? ? held = event : emit.call(event) }
         message = @provider.stream(messages: history, system: @system,
                                    tools: @tools.map(&:spec), signal: signal,
-                                   output_schema: output_schema, &emit)
+                                   output_schema: output_schema, &gate)
         attempt += 1
-        error = turn_error(message)
+        error = @retries&.error_for(message)
         if retry_turn?(error, attempt, signal)
           pause = @retries.delay(attempt, error["retry_after"])
           record_retry(message, error, attempt, pause, &emit)
           wait(pause, signal)
           next unless signal&.aborted?
         end
+        emit&.call(held) if held
         @session.append_message(message)
         return message
       end
     end
 
-    # The provider's own error when the turn failed, or a synthesized one
-    # for a completion that answers nothing: providers intermittently stop
-    # with an empty candidate, and a retry usually clears it.
-    def turn_error(message)
-      return message.error if message.stop_reason == StopReason::ERROR
-
-      EMPTY_COMPLETION_ERROR if empty_completion?(message)
-    end
-
-    def empty_completion?(message)
-      message.stop_reason == StopReason::STOP &&
-        message.content.all? { |block| block.is_a?(Content::Text) && block.text.to_s.strip.empty? }
-    end
-
     def retry_turn?(error, attempt, signal)
       return false unless @retries && error
       return false if signal&.aborted?
@@ -258,7 +261,8 @@ module Mistri
                                "delay" => pause.round(2))
       note = format("attempt %<attempt>d failed; retrying in %<pause>.1fs",
                     attempt: attempt, pause: pause)
-      emit&.call(Event.new(type: :retry, content: note, reason: StopReason::ERROR,
+      emit&.call(Event.new(type: :retry, content: note, attempt: attempt,
+                           max_attempts: @retries.attempts, delay: pause.round(2),
                            message: message))
     end
 
@@ -270,37 +274,44 @@ module Mistri
 
     # Answer or park the assistant's tool calls. Ungated calls execute (only
     # on a genuine tool_use turn with no abort; otherwise they pair with
-    # interrupted results). Gated calls park as approval requests and are
-    # returned, so the loop can suspend. Nothing is left dangling either way.
+    # interrupted results). Gated calls park as approval requests. Nothing
+    # is left dangling either way. Returns the parked calls and whether an
+    # executed tool ends the turn; a parked call outranks an executed
+    # ends_turn, because a suspension is the stronger stop and the model
+    # regains the floor when the run resumes.
     def run_tools(assistant, signal, &emit)
       calls = assistant.tool_calls
       unless assistant.stop_reason == StopReason::TOOL_USE && !signal&.aborted?
         calls.each { |call| answer(call, ToolExecutor::INTERRUPTED, &emit) }
-        return []
+        return [[], false]
       end
 
       parked, free = screen(calls, signal, &emit).partition { |call| gated?(call) }
-      execute(free, signal, &emit)
+      executed = execute(free, signal, &emit)
       parked.each do |call|
         @session.append("approval_request", "call" => call.to_h)
         emit&.call(Event.new(type: :approval_needed, tool_call: call))
       end
-      parked
+      [parked, executed.any? { |call| ends_turn?(call) }]
     end
 
+    # Returns the calls that actually executed (denied ones only answer).
     def settle(open, signal, &emit)
       approved, denied = open.partition { |approval| approval[:decision]["approved"] }
       cleared = screen(approved.map { |approval| approval[:call] }, signal, &emit)
-      execute(cleared, signal, &emit)
+      executed = execute(cleared, signal, &emit)
       denied.each do |approval|
         note = approval[:decision]["note"]
         text = "The user denied this tool call#{note ? ": #{note}" : "."}"
         answer(approval[:call], text, &emit)
       end
+      executed
     end
 
+    # Runs the calls and answers each; returns the calls that executed
+    # (blocked and parked calls never reach here).
     def execute(calls, signal, &emit)
-      return if calls.empty?
+      return [] if calls.empty?
 
       results = ToolExecutor.call(calls, @tools_by_name, signal: signal,
                                                          max_concurrency: @max_concurrency,
@@ -311,6 +322,7 @@ module Mistri
         result = rewrite(call, result, context) if @after_tool
         answer(call, result, duration: seconds, &emit)
       end
+      calls
     end
 
     # A blocked call answers in band, so the model reads the reason and
@@ -359,10 +371,22 @@ module Mistri
       tool ? tool.needs_approval?(call.arguments) : false
     end
 
-    def finished(message, usage)
+    def ends_turn?(call)
+      tool = @tools_by_name[call.name]
+      tool ? tool.ends_turn? : false
+    end
+
+    # A run stopped during its tool phase ends with a clean assistant
+    # message, so the message's stop reason alone would read :completed;
+    # the signal is what knows the user stopped it. handed_off marks a run
+    # an ends_turn tool ended, and only a genuinely completed one: a run
+    # aborted during that same tool phase handed nothing to anyone.
+    def finished(message, usage, signal = nil, handed_off: false)
       status = { StopReason::ABORTED => :aborted, StopReason::BUDGET => :budget,
                  StopReason::ERROR => :error }.fetch(message.stop_reason, :completed)
-      Result.new(message: message, status: status, usage: usage)
+      status = :aborted if status == :completed && signal&.aborted?
+      Result.new(message: message, status: status, usage: usage,
+                 handed_off: handed_off && status == :completed)
     end
 
     def suspended(message, parked, usage)
@@ -379,35 +403,6 @@ module Mistri
       Result.new(message: message, status: :budget, usage: usage)
     end
 
-    # Distinguishable from a parsed nil: JSON "null" is a valid value.
-    PARSE_FAILED = Object.new.freeze
-    private_constant :PARSE_FAILED
-
-    def task_input(input, schema)
-      "#{input}\n\nAnswer with ONLY a JSON value matching this schema:\n" \
-        "#{JSON.generate(Schema.strict(schema))}"
-    end
-
-    def parse_output(text)
-      body = text.to_s.strip
-      body = body[/\A```(?:json)?\s*(.*?)```\z/m, 1] || body
-      JSON.parse(body)
-    rescue JSON::ParserError
-      PARSE_FAILED
-    end
-
-    def task_errors(value, schema)
-      return ["the answer is not valid JSON"] if value.equal?(PARSE_FAILED)
-
-      Schema.violations(value, schema)
-    end
-
-    def fix_prompt(errors)
-      lines = errors.map { |error| "- #{error}" }.join("\n")
-      "Your answer did not satisfy the required output schema. Problems:\n" \
-        "#{lines}\nReply with ONLY the corrected JSON."
-    end
-
     def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 end

data/lib/mistri/child.rb

@@ -0,0 +1,130 @@
+# 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                # => :running, :done, :stopped, :failed
+  #   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"
+    # The states a worker can still be caught in: steerable, stoppable,
+    # worth waiting on.
+    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:)
+      @name = name
+      @session_id = session_id
+      @store = store
+    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
+    # 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.
+    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 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.
+    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))
+      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
+
+    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/compactor.rb

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

data/lib/mistri/console.rb

@@ -0,0 +1,188 @@
+# 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 !Child::LIVE.include?(status)
+          "#{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."
+        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
+      while Child::LIVE.include?(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"]}(#{JSON.generate(block["arguments"] || {})[0, 80]})"
+      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 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