mistri 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1414bffbf49921cf9e575ea1a8998cfc435b77325d80d55ed76e6564d63311c5
-  data.tar.gz: b707010a75d56d65a8c42b50a874807e0f529da6b5878246aa9b34239493c808
+  metadata.gz: 87b42895bd43efd658a542312836abdd62a3ee7b18ac9d2a3e289cef6b7752f3
+  data.tar.gz: 413e5fa28d123c5e8a6ec39e332149e4aaf5d6f0587a9c3947032a6a4bc83c2a
 SHA512:
-  metadata.gz: b7781114db5365b8ce899af9ab50b8eaf2279979d8110a282d54a4fb3187a2576fc94821c3ddb550e9af3da8052ad64b14310c5136d3a064044aee57418c209b
-  data.tar.gz: d87fb8db281d3c6cedaea995054723f4f15d62e5268384393e16d655dfd45ba714e4b276c73c378307e8b3314ecec1108b3d320578edd659d77e6d07a8e34e2f
+  metadata.gz: 36e337d37f8fa876bbb52ea4fcfe0d41f66bed3028acf84871e0fe9c6d743cb31a3916a1dea63235ff03fe1170731e134abb76f206e335b2f63e63f064e7086f
+  data.tar.gz: 45fb19f616d8fd5f4f90220eee76d807ce17ebd371bd4b36741c61f35156309664d986b3f020e36d1329748015250136406aa869d539e02339af1c3529c9cac0

data/CHANGELOG.md

@@ -5,6 +5,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-07-30
+
+- `Mistri.logger` and `Mistri::Sinks::Logger`: assign any Logger-compatible
+  object and every run logs its story as one scannable line per beat, tagged
+  by session (sub-agents get their worker label): the input, each tool call
+  and result with a short pairing id, arguments, duration, and result size,
+  each turn's token usage with cached prompt tokens called out, retries,
+  compaction, approvals (carrying the full call id `Session#approve` takes),
+  worker reports wherever a sink watched the spawn, and a closing line with
+  the run's outcome, elapsed time, turn count, and dollar cost whenever
+  pricing is known, a known $0.0000 included. `task` logs one frame around
+  all its fix passes, and the frame covers the whole public method, so store
+  and audit failures get a crash line too. Payloads log in full by default;
+  `content: false` keeps the same story as metadata only, error, crash, and
+  retry free text included, since exception messages can echo payloads. `level:` floors
+  the ordinary lines (warnings and errors keep their own levels, and
+  expected stops such as cancels and budget ceilings log calmly), `color:`
+  and `truncate:` are per-sink options, and a preconfigured `Sinks::Logger`
+  (subclasses included) can be assigned directly; wrong assignments and
+  options raise at configuration time. Sinks the Agent builds skip origin-tagged events so every agent, in
+  any process, logs its own events exactly once; a sink composed directly
+  per run renders forwarded child events with their origin instead. Logging
+  never breaks a run: sink construction and every write are contained,
+  failures warn once per run and the run's sink goes quiet, host exceptions
+  are never replaced (invalid byte sequences included), and hidden bytes in
+  payloads, names, ids, and labels render as visible escapes so untrusted
+  output cannot forge lines or steer a terminal. With no logger assigned
+  the event path is untouched (one nil check per run, nothing per event);
+  with one assigned, delta events short-circuit without allocating,
+  formatting is skipped when the floor level is disabled, and per-line
+  string work, tool argument keys and values included, is bounded by the
+  truncation limit, not the payload.
+
 ## [0.6.1] - 2026-07-21
 
 - The ActiveRecord store and workspace read past the host's query cache.
@@ -882,7 +915,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - Reserved the gem name.
 
-[Unreleased]: https://github.com/mcheemaa/mistri/compare/v0.6.1...HEAD
+[Unreleased]: https://github.com/mcheemaa/mistri/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/mcheemaa/mistri/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/mcheemaa/mistri/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/mcheemaa/mistri/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/mcheemaa/mistri/compare/v0.4.1...v0.5.0

data/README.md

@@ -231,6 +231,64 @@ The same event stream works in Sinatra, Rack, a WebSocket server, a background
 job, or a test. Event types form an extensible union; consumers should handle
 the types they use and ignore the rest.
 
+## Logging
+
+One assignment makes every run tell its story in your log:
+
+```ruby
+Mistri.logger = Rails.logger   # or any Logger-compatible object
+```
+
+```text
+[mistri 0a1b2c3d] run "What is 2 plus 3?" (gpt-5.6, 3 tools)
+[mistri 0a1b2c3d] turn 1 done tool_use (312 in / 48 out)
+[mistri 0a1b2c3d] tool add#7f3a {"a":2,"b":3}
+[mistri 0a1b2c3d] tool add#7f3a ok 12ms "5"
+[mistri 0a1b2c3d] text "The sum is 5."
+[mistri 0a1b2c3d] turn 2 done stop (410 in / 22 out)
+[mistri 0a1b2c3d] done completed in 1.2s, 2 turns, 722 in / 70 out, $0.0042
+```
+
+A turn line lands when the model finishes speaking, so it precedes the tool
+executions that turn requested. The short `#id` on tool lines pairs
+concurrent same-name calls; an `approval needed` line carries the full call
+id, which is what `session.approve` takes. Failed tools and retries log at
+warn and provider errors at error, while expected stops (a cancel, a budget
+ceiling) log calmly. Cached prompt tokens count toward "in" and are called
+out, dollar cost appears whenever pricing is known (including a known
+$0.0000), and hidden bytes in any value render as visible escapes.
+Sub-agents log under their own worker label (`[mistri researcher#89bb20de]`)
+exactly once, whichever process runs them; a `worker` report line appears
+wherever a sink watched the spawn. Interleaved lines stay whole as long as
+the logger serializes writes, which stdlib `Logger` and Rails' do. A `task`
+logs one frame around all its fix passes.
+
+By default the lines carry payloads: inputs, thinking, arguments, results.
+That is the point in development, and it is fine in production too when
+your log pipeline is where you want the story (shipping these lines to your
+log platform gives you agent observability for free). When payloads must
+stay out of a log, `content: false` keeps the whole story as metadata:
+names, ids, durations, sizes, tokens, cost, and statuses, and error, crash,
+and retry text reduces to its byte size while classes and reasons stay. `level: :debug`
+floors the ordinary lines, `truncate` bounds rendered values, and a wrong
+assignment raises at assignment time:
+
+```ruby
+Mistri.logger = Mistri::Sinks::Logger.new(logger, content: false, level: :debug)
+```
+
+Composing per run (`agent.run(input, &Mistri::Sinks::Logger.new(logger))`)
+is deliberately smaller: event lines under a bare `[mistri]` tag, no
+framing, and forwarded child events rendered with their origin, since no
+child sink exists to log them. Logger calls are synchronous on
+the run's own threads, so a slow logger slows the run: keep the destination
+local (stdout, a file) and let your log shipper make the network hop, or
+buffer at the logger layer. Logging never breaks a run: construction and
+every write are contained, and a failing logger warns once per run and that
+run's sink goes quiet. With no logger assigned the cost is one nil check
+per run; with one assigned, delta events short-circuit without allocating
+and per-line work is bounded by the truncation limit, not the payload.
+
 ## Long conversations and structured tasks
 
 Compaction is on by default for catalogued models. When a session enters the

data/lib/mistri/agent.rb

@@ -39,10 +39,12 @@ module Mistri
     # when an approved call finally executes, so a decision that aged days
     # still passes current policy); after_tool(call, result, context) may
     # return a replacement result, or nil to keep the original.
+    # log_label tags this agent's log lines (sub-agents
+    # get their worker label); nil falls back to the session id.
     def initialize(provider:, session: nil, system: nil, tools: [], budget: nil,
                    max_concurrency: 4, transform_context: nil, compaction: Compaction.new,
                    retries: RetryPolicy.new, skills: [], before_tool: nil, after_tool: nil,
-                   context: nil)
+                   context: nil, log_label: nil)
       @provider = provider
       @session = session || Session.new(store: Stores::Memory.new)
       skills = skills.is_a?(String) ? Skills.load(skills) : Array(skills)
@@ -62,6 +64,8 @@ module Mistri
       @before_tool = before_tool
       @after_tool = after_tool
       @context = context
+      @log_label = log_label
+      @log_depth = 0
     end
 
     attr_reader :session
@@ -73,18 +77,22 @@ module Mistri
     # schema, natively where the provider supports it. task adds validation
     # on top; run alone does not validate.
     def run(input, images: [], signal: nil, output_schema: nil, &emit)
-      if refresh_tool_control.any?
-        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"
-      end
+      # The frame covers the whole public method, so an audit rejection or
+      # a store failure gets a crash line too, not just loop failures.
+      logged(emit, verb: "run", input: input) do |subscriber|
+        if refresh_tool_control.any?
+          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"
+        end
 
-      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)
+        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, &subscriber)
+      end
     end
 
     # Continue a suspended run. Undecided approvals return immediately, still
@@ -93,25 +101,27 @@ module Mistri
     # 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 = refresh_tool_control
-      pending = open.select { |approval| approval[:decision].nil? }
-      if pending.any?
-        return Result.new(message: nil, status: :awaiting_approval,
+      logged(emit, verb: "resume") do |subscriber|
+        open = refresh_tool_control
+        pending = open.select { |approval| approval[:decision].nil? }
+        if pending.any?
+          next Result.new(message: nil, status: :awaiting_approval,
                           pending: pending.map { |approval| approval[:call] },
                           usage: Usage.zero)
-      end
+        end
 
-      executed = settle(open, signal, &emit)
-      if signal&.aborted?
-        last = @session.messages.reverse_each.find(&:assistant?)
-        return finished(last, Usage.zero, signal)
-      end
-      if executed.any? { |call| ends_turn?(call) }
-        last = @session.messages.reverse_each.find(&:assistant?)
-        return finished(last, Usage.zero, signal, handed_off: true)
-      end
+        executed = settle(open, signal, &subscriber)
+        if signal&.aborted?
+          last = @session.messages.reverse_each.find(&:assistant?)
+          next finished(last, Usage.zero, signal)
+        end
+        if executed.any? { |call| ends_turn?(call) }
+          last = @session.messages.reverse_each.find(&:assistant?)
+          next finished(last, Usage.zero, signal, handed_off: true)
+        end
 
-      loop_turns(signal, nil, &emit)
+        loop_turns(signal, nil, &subscriber)
+      end
     end
 
     # Run an exchange that must end in a JSON value matching schema. Tools
@@ -126,7 +136,37 @@ module Mistri
     # 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)
-      plan = Schema.task_plan(schema)
+      # One log frame for the whole task, fix passes included: the inner
+      # runs see the frame open and only tee, so the single done line
+      # reports the validated outcome, not a rejected intermediate answer.
+      logged(emit, verb: "task", input: input) do |subscriber|
+        plan = Schema.task_plan(schema)
+        validated_task(input, plan, images, signal, fixes, &subscriber)
+      end
+    end
+
+    # How full the context is: {tokens:, window:, fraction:}. Hosts render
+    # meters and near-limit warnings from this; window is nil for models the
+    # catalog does not know unless Compaction#window supplies one.
+    def context_usage
+      tokens = @session.context_tokens
+      window = context_window
+      { tokens: tokens, window: window,
+        fraction: window && (tokens.to_f / window).round(3) }
+    end
+
+    # Compact now (a UI button, a pre-flight trim before a big task). Returns
+    # the Compactor result, or nil when there is nothing worth compacting.
+    def compact(&)
+      Compactor.call(session: @session, provider: @provider,
+                     settings: @compaction || Compaction.new, &)
+    end
+
+    private
+
+    # The body of task, extracted so its early returns close the log frame
+    # instead of skipping it.
+    def validated_task(input, plan, images, signal, fixes, &emit)
       result = run(
         TaskOutput.prompt(input, plan), images:, signal:, output_schema: plan, &emit
       )
@@ -146,24 +186,47 @@ module Mistri
       end
     end
 
-    # How full the context is: {tokens:, window:, fraction:}. Hosts render
-    # meters and near-limit warnings from this; window is nil for models the
-    # catalog does not know unless Compaction#window supplies one.
-    def context_usage
-      tokens = @session.context_tokens
-      window = context_window
-      { tokens: tokens, window: window,
-        fraction: window && (tokens.to_f / window).round(3) }
+    # When a host sets Mistri.logger, every public run tees its events into
+    # a fresh logging sink for this session alongside the caller's block,
+    # and the framing lines carry what the stream cannot: the input, the
+    # model, and the final Result. Nothing wraps when no logger is set, a
+    # nested public call (task's inner runs) reuses the open frame, and a
+    # caller's subscriber failures propagate exactly as before because the
+    # sink never raises.
+    def logged(emit, verb:, input: nil)
+      sink = log_sink
+      return yield(emit) unless sink
+
+      @log_depth += 1
+      begin
+        sink.run_started(verb: verb, input: input, model: @provider.model,
+                         tool_count: @tools.length)
+        subscriber = if emit
+                       lambda { |event|
+                         sink.call(event)
+                         emit.call(event)
+                       }
+                     else
+                       sink.to_proc
+                     end
+        begin
+          result = yield(subscriber)
+        rescue StandardError => e
+          sink.run_crashed(EventDelivery.original(e))
+          raise
+        end
+        sink.run_finished(result)
+        result
+      ensure
+        @log_depth -= 1
+      end
     end
 
-    # Compact now (a UI button, a pre-flight trim before a big task). Returns
-    # the Compactor result, or nil when there is nothing worth compacting.
-    def compact(&)
-      Compactor.call(session: @session, provider: @provider,
-                     settings: @compaction || Compaction.new, &)
-    end
+    def log_sink
+      return nil if @log_depth.positive?
 
-    private
+      Sinks::Logger.attach(@session.id, label: @log_label)
+    end
 
     def loop_turns(signal, output_schema = nil, &emit)
       turns = 0

data/lib/mistri/sinks/logger.rb

@@ -0,0 +1,401 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Sinks
+    # Renders the event stream as one log line per meaningful beat, so a
+    # log tells each run's whole story: which tools ran with which
+    # arguments, how long each took, what every turn cost, and how the run
+    # ended. Deltas never log (whole blocks do).
+    #
+    # Assigning Mistri.logger turns this on for every run in one line:
+    #
+    #   Mistri.logger = Rails.logger
+    #   Mistri.logger = Mistri::Sinks::Logger.new(logger, color: true)
+    #
+    # Payloads (inputs, text, thinking, arguments, results, reports) log in
+    # full by default; content: false keeps the same story with metadata
+    # only, for logs whose payloads must stay out. level: floors the
+    # ordinary lines (warnings and errors keep their own levels).
+    #
+    # Sinks the Agent builds through for_session skip origin-tagged events,
+    # because every agent logs its own events under its own tag: exactly
+    # once, however deep the nesting and whichever process runs it. A sink
+    # composed directly (agent.run(input, &sink)) is the only logger its
+    # run has, so it renders forwarded child events instead, origin first;
+    # framing (run, done) still comes only from the Agent.
+    #
+    # Any object responding to info/warn/error works. Logging must never
+    # break a run: every entry point rescues, the first failure warns, and
+    # the sink goes quiet for the rest of its run. Tool events arrive from
+    # executor threads; the only mutable state (the turn counter) moves on
+    # loop-thread events, and interleaved lines stay whole as long as the
+    # host's logger serializes writes, which stdlib Logger and Rails do.
+    class Logger
+      SKIPPED = %i[start text_start text_delta thinking_start thinking_delta
+                   toolcall_start toolcall_delta toolcall_end].to_h { |type| [type, true] }.freeze
+      LINES = { text_end: :text_line, thinking_end: :thinking_line,
+                tool_started: :tool_line, tool_result: :tool_result_line,
+                done: :turn_line, error: :error_line, retry: :retry_line,
+                approval_needed: :approval_line, compacting: :compacting_line,
+                compaction: :compaction_line, subagent_report: :report_line }.freeze
+      QUIET = %i[text_end thinking_end tool_started done approval_needed
+                 compacting compaction subagent_report].to_h { |type| [type, true] }.freeze
+      COLORS = { bold: "1", dim: "2", red: "31", green: "32", yellow: "33" }.freeze
+      LEVELS = %i[debug info warn error].freeze
+      # C0 and C1 controls, DEL, Unicode line and paragraph separators, and
+      # bidi embedding controls: everything that could steer a terminal or
+      # forge a line while staying invisible.
+      HIDDEN = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/
+      HEAD = 4096
+      private_constant :SKIPPED, :LINES, :QUIET, :COLORS, :LEVELS, :HIDDEN, :HEAD
+
+      # truncate bounds every rendered value (nil for full payloads).
+      # session is the line tag, verbatim, so concurrent runs stay
+      # distinguishable. Options are validated here so a bad configuration
+      # fails at assignment time, not silently at run time.
+      def initialize(logger, session: nil, truncate: 200, color: false, level: :info,
+                     content: true, forwarded: :render)
+        raise ArgumentError, "level must be one of #{LEVELS.join(", ")}" unless
+          LEVELS.include?(level)
+        unless truncate.nil? || (truncate.is_a?(Integer) && truncate.positive?)
+          raise ArgumentError, "truncate must be a positive Integer or nil"
+        end
+        raise ArgumentError, "forwarded must be :render or :skip" unless
+          %i[render skip].include?(forwarded)
+
+        @logger = logger
+        @truncate = truncate
+        @color = color
+        @level = level
+        @content = content
+        @forwarded = forwarded
+        @session = session && field(session, limit: 48)
+        @turns = 0
+        @started = now
+        @warned = false
+        @tag = paint(@session ? "[mistri #{@session}]" : "[mistri]", :dim)
+      end
+
+      # A fresh sink for one run: same logger and options, this run's tag
+      # (a sub-agent's label, or the session id), its own turn count and
+      # clock. Runs framed this way skip forwarded events, because each
+      # agent in the tree logs its own.
+      def for_session(id, label: nil)
+        self.class.new(@logger, session: label || id.to_s[0, 8], truncate: @truncate,
+                                color: @color, level: @level, content: @content, forwarded: :skip)
+      end
+
+      # The global hookup: builds this run's sink from Mistri.logger, or
+      # nil. Contained, so a broken assignment costs the log, never the run.
+      def self.attach(id, label: nil)
+        configured = Mistri.logger
+        return nil unless configured
+
+        sink = configured.is_a?(self) ? configured : new(configured)
+        sink.for_session(id, label: label)
+      rescue StandardError => e
+        warn "mistri: logging sink construction failed (#{e.class}: #{e.message}); run not logged"
+        nil
+      end
+
+      def call(event)
+        return if @warned
+
+        return if event.origin && (@forwarded == :skip)
+        return if SKIPPED[event.type]
+        return if QUIET[event.type] && !floor_enabled?
+
+        handler = LINES[event.type]
+        prefix = event.origin ? "#{field(event.origin)} " : ""
+        # Future event types degrade to a greppable line, never to silence.
+        line = handler ? send(handler, event) : "#{event.type} #{body_of(event.content)}".rstrip
+        write("#{prefix}#{line.first}", level: line.last) if line.is_a?(Array)
+        write("#{prefix}#{line}") if line.is_a?(String)
+      rescue StandardError => e
+        quiet(e)
+      end
+
+      def to_proc = method(:call).to_proc
+
+      # The framing the stream cannot carry: the Agent calls these around a
+      # run with the input, the model, and the final Result. Each is total
+      # for the same reason call is: a logging failure inside a rescue
+      # block must never replace the host's own exception.
+      def run_started(verb:, model:, tool_count:, input: nil)
+        @turns = 0
+        @started = now
+        return unless floor_enabled?
+
+        ask = input && @content ? %( "#{trim(input)}") : ""
+        write("#{paint(verb, :bold)}#{ask} (#{field(model)}, #{count(tool_count, "tool")})")
+      rescue StandardError => e
+        quiet(e)
+      end
+
+      def run_finished(result)
+        status, level = status_of(result)
+        return if level == :info && !floor_enabled?
+
+        write("#{paint("done", :bold)} #{status} in #{clock(now - @started)}, " \
+              "#{count(@turns, "turn")}#{summary(result.usage)}", level: level)
+      rescue StandardError => e
+        quiet(e)
+      end
+
+      def run_crashed(error)
+        write("#{paint("crashed", :red)} #{error.class}#{note(error.message)}", level: :error)
+      rescue StandardError => e
+        quiet(e)
+      end
+
+      private
+
+      def text_line(event)
+        body = body_of(event.content)
+        body.empty? ? nil : "text #{body}"
+      end
+
+      def thinking_line(event)
+        body = body_of(event.content)
+        body.empty? ? nil : "thinking #{body}"
+      end
+
+      def tool_line(event)
+        "tool #{title(event.tool_call)} #{arguments(event.tool_call)}".rstrip
+      end
+
+      def tool_result_line(event)
+        verdict = event.tool_error? ? paint("FAILED", :red) : "ok"
+        parts = ["tool #{title(event.tool_call)} #{verdict}", clock(event.duration),
+                 presence(body_of(event.content))]
+        [parts.compact.join(" "), event.tool_error? ? :warn : :info]
+      end
+
+      def turn_line(event)
+        @turns += 1
+        "turn #{@turns} done #{event.reason}#{tokens(event.message&.usage)}"
+      end
+
+      # :error also carries expected stops, which log calmly; only real
+      # failures alarm. A budget stop is synthetic (no provider call), so
+      # it alone does not count as a turn.
+      def error_line(event)
+        case event.reason
+        when StopReason::BUDGET then ["stopped on budget", :warn]
+        when StopReason::ABORTED
+          @turns += 1
+          "aborted"
+        else
+          @turns += 1
+          ["#{paint("error", :red)} #{event.reason}#{note(event.error_message)}", :error]
+        end
+      end
+
+      def retry_line(event)
+        wait = event.delay ? " in #{event.delay.round(1)}s" : ""
+        ["#{paint("retry", :yellow)} #{event.attempt}/#{event.max_attempts}#{wait}" \
+         "#{note(event.content)}", :warn]
+      end
+
+      # The full call id rides the line: Session#approve takes exactly that
+      # id, and the short pairing suffix is not it.
+      def approval_line(event)
+        call = event.tool_call
+        parts = ["approval needed #{title(call)}", presence(arguments(call)),
+                 "id #{field(call.id, limit: 128)}"]
+        parts.compact.join(" ")
+      end
+
+      def compacting_line(_event) = "compacting"
+
+      def compaction_line(event) = "compacted #{body_of(event.content)}"
+
+      def report_line(event)
+        "worker #{field(event.agent)} (#{field(event.session_id.to_s[0, 8], limit: 16)}) " \
+        "#{event.status} #{body_of(event.content)}".rstrip
+      end
+
+      def status_of(result)
+        case result.status
+        when :completed
+          [result.handed_off? ? "completed (handed off)" : "completed", :info]
+        when :awaiting_approval
+          ["suspended (#{count(result.pending.length, "approval")} pending)", :info]
+        when :aborted then ["aborted", :info]
+        when :budget then ["stopped on budget", :warn]
+        else [paint(result.status.to_s, :red), :error]
+        end
+      end
+
+      def summary(usage)
+        return "" unless usage
+
+        base = ", #{prompt(usage)} / #{usage.output} out"
+        cost = usage.cost
+        cost&.known? ? base + format(", $%.4f", cost.total) : base
+      end
+
+      def tokens(usage)
+        usage ? " (#{prompt(usage)} / #{usage.output} out)" : ""
+      end
+
+      # Cache traffic is real prompt volume; input alone under-reports it.
+      def prompt(usage)
+        cached = usage.cache_read + usage.cache_write
+        return "#{usage.input} in" unless cached.positive?
+
+        "#{usage.input + cached} in (#{cached} cached)"
+      end
+
+      # A short call id makes concurrent same-name calls pairable.
+      def title(tool_call)
+        return paint("?", :green) unless tool_call
+
+        name = paint(field(tool_call.name), :green)
+        id = field(tool_call.id, limit: 128)
+        ref = id.length > 4 ? id[-4, 4] : id
+        ref.empty? ? name : "#{name}##{ref}"
+      end
+
+      def arguments(tool_call)
+        return "[#{trim(tool_call.arguments_error)}]" if tool_call.arguments_error?
+        return "" unless @content
+
+        rendered = +""
+        preview(tool_call.arguments || {}, rendered)
+        trim(rendered)
+      end
+
+      # A bounded JSON preview: rendering stops once the budget is spent,
+      # so a payload near the 8 MiB argument ceiling never materializes as
+      # a whole serialized string on the emission path.
+      def preview(value, out)
+        return out << "..." if @truncate && out.length > @truncate
+
+        case value
+        when Hash
+          walk(value, out, "{", "}") do |(key, item)|
+            out << JSON.generate(snip(key.to_s)) << ":"
+            preview(item, out)
+          end
+        when Array
+          walk(value, out, "[", "]") { |item| preview(item, out) }
+        when String
+          out << JSON.generate(snip(value))
+        else
+          out << JSON.generate(value)
+        end
+      end
+
+      def snip(text) = @truncate ? text[0, @truncate] : text
+
+      def walk(items, out, open, close)
+        out << open
+        items.each_with_index do |item, index|
+          break if @truncate && out.length > @truncate && index.positive?
+
+          out << "," if index.positive?
+          yield(item)
+        end
+        out << close
+      end
+
+      # Diagnostics keep their class and reason in every mode; the free
+      # text obeys content:, because exception messages can echo payloads.
+      def note(text)
+        flat = presence(trim(text))
+        return "" unless flat
+
+        @content ? ": #{flat}" : " (#{bytes(text)})"
+      end
+
+      # content: false keeps the beat and the volume, never the words.
+      def body_of(text)
+        return "" if text.nil? || text.to_s.strip.empty?
+        return "(#{bytes(text)})" unless @content
+
+        quote(text)
+      end
+
+      def quote(text)
+        body, cut = clip(text)
+        cut ? %("#{body}" (#{bytes(text)})) : %("#{body}")
+      end
+
+      def trim(text) = clip(text).first
+
+      # Structural scalars (tags, names, ids, labels) are bounded and
+      # stripped of hidden bytes before they join a line, so untrusted
+      # values cannot forge lines or steer a terminal.
+      def field(value, limit: 64)
+        clip(value, limit: limit).first
+      end
+
+      # String work per line stays bounded: only a head of the payload is
+      # normalized, never all of it. scrub repairs invalid bytes (encode
+      # alone skips same-encoding validation), encode converts binary, and
+      # hidden bytes become visible escapes. The size suffix reports the
+      # whole payload.
+      def clip(text, limit: @truncate)
+        raw = text.to_s
+        head = limit ? raw[0, [(limit * 2) + 1, HEAD].max] : raw
+        flat = head.scrub.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+                   .gsub(/\s+/, " ").strip
+                   .gsub(HIDDEN) { |hidden| format("\\u%04x", hidden.ord) }
+        cut = limit && (flat.length > limit || head.bytesize < raw.bytesize)
+        return [flat, false] unless cut
+
+        ["#{flat[0, limit].rstrip}...", true]
+      end
+
+      def clock(duration)
+        return nil unless duration
+
+        duration < 1 ? "#{(duration * 1000).round}ms" : "#{duration.round(1)}s"
+      end
+
+      def bytes(text)
+        size = text.to_s.bytesize
+        return "#{size}B" if size < 1024
+
+        size < 1_048_576 ? format("%.1fKB", size / 1024.0) : format("%.1fMB", size / 1_048_576.0)
+      end
+
+      def count(number, noun) = "#{number} #{number == 1 ? noun : "#{noun}s"}"
+
+      def presence(text) = text.nil? || text.empty? ? nil : text
+
+      def paint(text, color) = @color ? "\e[#{COLORS.fetch(color)}m#{text}\e[0m" : text
+
+      # Formatting is skipped entirely when the floor level is disabled on
+      # the host logger; warnings and errors always go through.
+      def floor_enabled?
+        query = :"#{@level}?"
+        !@logger.respond_to?(query) || @logger.public_send(query)
+      rescue StandardError
+        true
+      end
+
+      def write(line, level: :info)
+        return if @warned
+
+        level = @level if level == :info
+        @logger.public_send(level, "#{@tag} #{line}")
+      rescue StandardError => e
+        quiet(e)
+      end
+
+      def quiet(error)
+        return if @warned
+
+        @warned = true
+        warn "mistri: logging sink failed (#{error.class}: #{error.message}); " \
+             "logging disabled for this run"
+      end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/mistri/sub_agent/execution.rb

@@ -58,9 +58,9 @@ module Mistri
 
       def run_child_agent(child:, label:, provider:, system:, tools:, task:, schema:,
                           signal:, emit:, agent_options:)
-        agent = Agent.new(provider: provider, session: child, system: system,
-                          tools: tools, **agent_options)
         origin = "#{label}##{child.id[0, 8]}"
+        agent = Agent.new(provider: provider, session: child, system: system,
+                          tools: tools, log_label: origin, **agent_options)
         tagged = ->(event) { forward(event, origin, emit) }
         return agent.task(task, schema: schema, signal: signal, &tagged) if schema
 

data/lib/mistri/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mistri
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/mistri.rb

@@ -51,6 +51,7 @@ require_relative "mistri/mcp"
 require_relative "mistri/sinks/action_cable"
 require_relative "mistri/sinks/sse"
 require_relative "mistri/sinks/coalesced"
+require_relative "mistri/sinks/logger"
 require_relative "mistri/providers/fake"
 require_relative "mistri/providers/anthropic"
 require_relative "mistri/providers/openai"
@@ -66,8 +67,25 @@ module Mistri
                   gemini: "GEMINI_API_KEY" }.freeze
 
   # The configured lock adapter, nil until a host sets one. See Locks.
+  # The run logger, nil until a host sets one: a Logger-compatible object
+  # (info/warn/error), or a Sinks::Logger for options. Every Agent run
+  # then logs its story. A wrong assignment raises here, where the typo
+  # is, instead of leaving every run's log silently empty.
   class << self
     attr_accessor :locks
+    attr_reader :logger
+
+    def logger=(value)
+      sink_like = value.is_a?(Sinks::Logger)
+      logger_like = %i[info warn error].all? { |severity| value.respond_to?(severity) }
+      unless value.nil? || sink_like || logger_like
+        raise ConfigurationError,
+              "Mistri.logger takes a Logger-compatible object (info/warn/error) " \
+              "or a Mistri::Sinks::Logger"
+      end
+
+      @logger = value
+    end
   end
 
   module_function

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mistri
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Muhammad Ahmed Cheema
@@ -90,6 +90,7 @@ files:
 - lib/mistri/session.rb
 - lib/mistri/sinks/action_cable.rb
 - lib/mistri/sinks/coalesced.rb
+- lib/mistri/sinks/logger.rb
 - lib/mistri/sinks/sse.rb
 - lib/mistri/skill.rb
 - lib/mistri/skills.rb
@@ -134,7 +135,7 @@ metadata:
   changelog_uri: https://github.com/mcheemaa/mistri/blob/main/CHANGELOG.md
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
-  documentation_uri: https://github.com/mcheemaa/mistri/blob/v0.6.1/docs/README.md
+  documentation_uri: https://github.com/mcheemaa/mistri/blob/v0.7.0/docs/README.md
   bug_tracker_uri: https://github.com/mcheemaa/mistri/issues
 rdoc_options: []
 require_paths: