scout-ai 1.2.3 → 2.0.0

data/scout_commands/llm/prov

@@ -0,0 +1,602 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'scout-ai'
+require 'json'
+require 'set'
+require 'tempfile'
+
+cmd = $previous_commands ?
+  "scout #{$previous_commands.any? ? "#{$previous_commands * ' '} " : ''}#{File.basename(__FILE__)}" :
+  $PROGRAM_NAME
+
+options = SOPT.setup <<~EOF
+
+Examine the provenance of a chat or workflow job
+
+$ #{cmd} [<options>] <filename>
+
+-h--help Print this help
+-c--component Show per-component direct costs instead of aggregate totals
+-f--flow Print a compact provenance flow
+-l--long Show full filesystem paths instead of abbreviated names
+-e--evidence List the deduplicated direct inference events and their evidence
+--dot* Write the flow as Graphviz DOT
+-p--plot* Render the flow as svg, png, or pdf
+EOF
+if options[:help]
+  defined?(scout_usage) ? scout_usage : puts(SOPT.doc)
+  exit 0
+end
+
+component = options.delete(:component)
+flow = options.delete(:flow)
+dot_file = options.delete(:dot)
+plot_file = options.delete(:plot)
+long = options.delete(:long)
+evidence = options.delete(:evidence)
+filename = ARGV.first
+raise MissingParameterException, :filename if filename.nil?
+
+# A persisted Step always has an info sidecar. A .files directory alone is NOT
+# evidence: saved agent chats carry one too. Explicitly loading the Step after
+# this evidence check avoids treating every readable chat as a job.
+job_evidence = Open.exists?(filename + '.info')
+root_type = job_evidence ? :job : :chat
+root = root_type == :job ? Step.load(filename) : Path.setup(File.expand_path(filename))
+warnings = []
+records = Chat.traverse_provenance(
+  root,
+  root_type: root_type,
+  on_error: lambda do |error, kind, object, relation, reference|
+    warnings << {
+      error: error,
+      kind: kind,
+      object: object,
+      relation: relation,
+      reference: reference
+    }
+  end
+).to_a
+
+# ------------------------------------------------------------------
+# Build graph: nodes keyed by [kind, path], edges as {from, to, relation}
+# ------------------------------------------------------------------
+nodes = {}
+edges = []
+records.each do |kind, object, parent_kind, parent, relation, first_visit, _detail|
+  key = Chat.provenance_key(kind, object)
+  nodes[key] ||= { kind: kind, object: object, path: Chat.provenance_path(kind, object) }
+  next unless parent
+
+  parent_key = Chat.provenance_key(parent_kind, parent)
+  nodes[parent_key] ||= {
+    kind: parent_kind,
+    object: parent,
+    path: Chat.provenance_path(parent_kind, parent)
+  }
+  edge = { from: parent_key, to: key, relation: relation, first_visit: first_visit }
+  edges << edge unless edges.any? do |other|
+    other[:from] == edge[:from] && other[:to] == edge[:to] && other[:relation] == relation
+  end
+end
+root_key = Chat.provenance_key(root_type, root)
+
+# Adjacency: parent -> children, sorted for readability
+adjacency = Hash.new { |h, k| h[k] = [] }
+edges.each do |edge|
+  adjacency[edge[:from]] << edge
+end
+RELATION_ORDER = { dependency: 0, log: 1, job: 2, agent_job: 3, result: 4 }
+adjacency.each_value do |children|
+  children.sort_by! { |e| RELATION_ORDER[e[:relation]] || 99 }
+end
+
+# ------------------------------------------------------------------
+# Token computation
+# ------------------------------------------------------------------
+chat_cache = {}
+
+# Direct tokens for a single node:
+#   chat  -> its own direct inference tokens
+#   job   -> sum of tokens from its direct log chats (agent.chat + society chats)
+direct_tokens = lambda do |key|
+  node = nodes[key]
+  if node[:kind] == :chat
+    chat = chat_cache[node[:path]] ||= Chat.load(node[:path])
+    Chat.token_totals([chat])
+  else
+    logs = edges.select { |e| e[:from] == key && e[:relation] == :log }
+                .collect { |e| nodes[e[:to]][:path] }.uniq
+    chats = logs.collect { |path| chat_cache[path] ||= Chat.load(path) }
+    Chat.token_totals(chats)
+  end
+rescue => error
+  warnings << { error: error, kind: node[:kind], object: node[:object], relation: :tokens }
+  Chat::TOKEN_KEYS.each_with_object({}) { |name, totals| totals[name.to_sym] = 0 }
+end
+
+# ------------------------------------------------------------------
+# Receipt (agent_meta) evidence: delegated inference events embedded in
+# function_call_output envelopes.  Problems are collected, never fatal.
+# ------------------------------------------------------------------
+receipt_warnings = []
+token_events = nil
+token_events_for = lambda do
+  return token_events unless token_events.nil?
+  token_events = begin
+    Chat.provenance_token_events(root, warnings: receipt_warnings)
+  rescue => error
+    warnings << { error: error, kind: root_type, object: root, relation: :tokens }
+    []
+  end
+end
+
+def receipt_evidence(event)
+  event[:evidence].select { |evidence| evidence[:origin] == :agent_meta }
+end
+
+# Receipt evidence grouped by the chat file that carries the envelope; used
+# for the one-line delegated annotations and to decide whether scope lines
+# are needed in component mode.
+receipt_events_by_source = Hash.new { |hash, key| hash[key] = [] }
+has_receipt_evidence = false
+token_events_for.call.each do |event|
+  next if receipt_evidence(event).empty?
+  has_receipt_evidence = true
+  receipt_evidence(event).collect { |evidence| evidence[:source] }.compact.uniq.each do |source|
+    receipt_events_by_source[source] << event
+  end
+end
+
+# Aggregate tokens: provenance-aware totals of the subtree reachable from the
+# node.  Direct inference events are deduplicated by identity, so usage that
+# exists only inside agent_meta receipts (delegated children whose logs were
+# never saved) is included without double counting.
+aggregate_cache = {}
+aggregate_tokens = lambda do |key|
+  return aggregate_cache[key] if aggregate_cache.key?(key)
+  node = nodes[key]
+  subtree = node[:kind] == :job ? node[:object] : node[:path]
+  aggregate_cache[key] = Chat.provenance_token_totals(subtree, warnings: receipt_warnings)
+rescue => error
+  Chat::TOKEN_KEYS.each_with_object({}) { |name, totals| totals[name.to_sym] = 0 }
+end
+
+# Whole-tree totals per scope; only meaningful when receipts exist.
+scope_totals = lambda do |scope|
+  Chat.provenance_token_totals(root, scope: scope, warnings: receipt_warnings)
+rescue => error
+  Chat::TOKEN_KEYS.each_with_object({}) { |name, totals| totals[name.to_sym] = 0 }
+end
+
+# Select mode: aggregate (default) or component (direct)
+node_tokens = component ? direct_tokens : aggregate_tokens
+
+# ------------------------------------------------------------------
+# Visibility: which nodes should be shown?
+# ------------------------------------------------------------------
+# Hidden nodes are skipped entirely — not printed and not traversed.
+#   - result-relation chats: they duplicate the job node and create cycles
+#   - top-level agent.chat log file: its cost is subsumed by the parent job.
+#     ScoutCoder: DUAL-LAYOUT. The root copy of the agent conversation sits
+#     directly under the files dir in BOTH layouts:
+#       new     <job>.files/agent.chat
+#       legacy  <job>.files/log/agent.chat
+#     Any basename agent.chat whose parent is a `<something>.files` directory
+#     (top level of the files dir) or the legacy `.../log` directory is such a
+#     copy.  NESTED society chats (agent.society/<agent>/<conv>/agent.chat,
+#     log/society/<agent>/<conv>/agent.chat) are real independent inferences
+#     and must be shown.
+def top_level_agent_chat?(path)
+  return false unless File.basename(path) == 'agent.chat'
+  parent = File.dirname(path)
+  parent.end_with?('/log') || parent.end_with?('/log/') ||
+    parent.end_with?('.files')
+end
+
+def hidden_node?(node, relation)
+  return true if relation == :result
+  return true if relation == :log && top_level_agent_chat?(node[:path])
+  false
+end
+
+# ------------------------------------------------------------------
+# Formatting helpers
+# ------------------------------------------------------------------
+def token_str(tokens)
+  parts = []
+  parts << "total=#{Misc.human_number(tokens[:tt])}" if tokens[:tt] && tokens[:tt].to_i > 0
+  parts << "prompt=#{Misc.human_number(tokens[:pt])}" if tokens[:pt] && tokens[:pt].to_i > 0
+  parts << "cont=#{Misc.human_number(tokens[:ct])}" if tokens[:ct] && tokens[:ct].to_i > 0
+  parts << "cache=#{Misc.human_number(tokens[:cct])}" if tokens[:cct] && tokens[:cct].to_i > 0
+  parts << "reason=#{Misc.human_number(tokens[:rt])}" if tokens[:rt] && tokens[:rt].to_i > 0
+  parts * ' '
+end
+
+def report_line(kind, label, tokens, offset: 0)
+  color = kind == :job ? :yellow : :green
+  parts = [' ' * (offset * 2)]
+  parts << Log.color(color, kind.to_s)
+  tok = token_str(tokens)
+  parts << tok unless tok.empty?
+  parts << Log.color(:blue, label.to_s) unless label.to_s.empty?
+  parts * ' '
+end
+
+def job_short_id(path)
+  basename = File.basename(path)
+
+  parts = basename.split('_')
+  if parts.length == 2 && parts.last.length > 10
+    parts.last[0,8]
+  else
+    basename
+  end
+end
+
+def node_label(node, parent_node = nil, root_key = nil, key = nil, long = false)
+  path = node[:path]
+  return path if long
+  if node[:kind] == :job
+    job = node[:object]
+    workflow = job.info[:workflow] || job.info['workflow']
+    task = job.info[:task_name] || job.info['task_name']
+    short_id = job_short_id(path)
+    workflow && task ? "#{workflow}/#{task} #{short_id}" : short_id
+  elsif parent_node && parent_node[:kind] == :job && path.include?('.files/log/')
+    # Log chat under a job: show path relative to the job's log directory.
+    # Derive log dir from parent_node path (which is the realpath) to avoid
+    # symlink-resolution mismatches between the Step object and node path.
+    parent_log_dir = File.join(parent_node[:path] + ".files", "log")
+    rel = Misc.path_relative_to(parent_log_dir, path)
+    rel.nil? || rel.empty? ? File.basename(path) : rel
+  elsif parent_node && parent_node[:kind] == :job && path.include?(parent_node[:path] + '.files/')
+    # ScoutCoder: DUAL-LAYOUT sibling of the legacy branch above.  Log chat
+    # under a job in the NEW layout (no log/ component): show the path
+    # relative to the job's files dir, so
+    # agent.society/Direct/harness_test/agent.chat is shown shortened.
+    parent_files_dir = parent_node[:path] + '.files'
+    rel = Misc.path_relative_to(parent_files_dir, path)
+    rel.nil? || rel.empty? ? File.basename(path) : rel
+  elsif key == root_key && node[:kind] == :chat
+    # Root chat: show basename
+    File.basename(path)
+  else
+    path
+  end
+end
+
+# ------------------------------------------------------------------
+# Tree rendering (default mode)
+# ------------------------------------------------------------------
+unless flow || dot_file || plot_file
+  printed = Set.new
+  print_tree = lambda do |key, offset, relation, parent_key|
+    # Skip already-visited nodes entirely (no "(seen)" line)
+    return if printed.include?(key)
+
+    node = nodes[key]
+    parent_node = parent_key ? nodes[parent_key] : nil
+
+    # Skip hidden nodes entirely — don't print, don't traverse children
+    return if hidden_node?(node, relation)
+
+    printed << key
+    label = node_label(node, parent_node, root_key, key, long)
+    # A job reached through an agent_meta receipt is a delegated producer.
+    label = "delegated-job #{label}" if node[:kind] == :job && relation == :agent_job
+    puts report_line(node[:kind], label, node_tokens.call(key), offset: offset)
+
+    # One compact annotation line for the delegated usage embedded in this
+    # chat's own outputs; never one line per receipt.
+    if node[:kind] == :chat
+      events = receipt_events_by_source.key?(node[:path]) ? receipt_events_by_source[node[:path]] : []
+      if events && events.any?
+        delegated_tt = events.inject(0) { |sum, event| sum + event[:tokens][:tt].to_i }
+        tools = events.flat_map do |event|
+          receipt_evidence(event).collect { |evidence| evidence[:tool_name] }
+        end.compact.uniq.sort
+        annotation = "delegated receipt: #{events.length} events, total=#{Misc.human_number(delegated_tt)}"
+        annotation += ", #{tools * ','}" unless tools.empty?
+        puts [(' ' * ((offset + 1) * 2)), Log.color(:cyan, annotation)] * ' '
+      end
+    end
+
+    (adjacency[key] || []).each do |edge|
+      print_tree.call(edge[:to], offset + 1, edge[:relation], key)
+    end
+  end
+  print_tree.call(root_key, 0, nil, nil)
+
+  # Component mode: make the evidence coverage behind the numbers explicit
+  # once receipts are present; chats without receipts keep the previous output
+  # exactly.  These are COVERAGE figures, not additive cost categories:
+  # chat_evidence + receipt_evidence double counts every event that exists in
+  # both a saved child log and a receipt.  Only deduplicated_total is the
+  # cost, and receipt_only is the disjoint delegated contribution.
+  if component && has_receipt_evidence
+    coverage = [[:deduplicated_total, 'total'],
+                [:chat_evidence, 'events with saved chat/log evidence'],
+                [:receipt_evidence, 'events inside agent_meta receipts (overlaps chat_evidence)'],
+                [:receipt_only, 'receipt evidence with no saved chat/log']]
+    coverage.each do |scope, note|
+      totals = scope_totals.call(scope)
+      rendered = token_str(totals)
+      rendered = 'total=0' if rendered.empty?
+      puts Log.color(:cyan, "evidence #{scope}:") + ' ' + rendered + ' ' + Log.color(:cyan, "(#{note})")
+    end
+
+    conflict_info = {}
+    Chat.provenance_token_totals(root, warnings: [], conflicts: conflict_info)
+    unless conflict_info[:authoritative]
+      puts Log.color(:red, 'unresolved identity conflicts: ') +
+        "#{conflict_info[:events]} conflicting event(s); totals above are best-effort (canonical evidence only), not exact"
+    end
+  end
+end
+
+# ------------------------------------------------------------------
+# Flow / DOT / SVG mode
+# ------------------------------------------------------------------
+# Convert root-outward discovery relations into natural data-flow arrows.
+flow_edges = edges.collect do |edge|
+  case edge[:relation]
+  when :job
+    { from: edge[:to], to: edge[:from], relation: :result }
+  when :agent_job
+    { from: edge[:to], to: edge[:from], relation: :delegated_result }
+  when :dependency
+    { from: edge[:to], to: edge[:from], relation: :dependency }
+  else
+    edge.slice(:from, :to, :relation)
+  end
+end.uniq
+
+if flow || dot_file || plot_file
+  # Determine visible nodes using same rules as tree mode.
+  hidden_keys = Set.new
+  nodes.each do |key, node|
+    # top-level agent.chat is hidden; nested ones are visible
+    hidden_keys << key if node[:kind] == :chat && top_level_agent_chat?(node[:path])
+    # result-relation chats that duplicate a job (same path)
+    if node[:kind] == :chat
+      has_job_same_path = nodes.any? do |k, n|
+        n[:kind] == :job && n[:path] == node[:path]
+      end
+      hidden_keys << key if has_job_same_path
+    end
+  end
+  visible_keys = nodes.keys.reject { |k| hidden_keys.include?(k) }
+  visible_set = Set.new(visible_keys)
+
+  # Jobs in dependency order, then chat files
+  job_keys = visible_keys.select { |kind, _path| kind == :job }
+  predecessors = Hash.new { |hash, k| hash[k] = [] }
+  flow_edges.each do |edge|
+    predecessors[edge[:to]] << edge[:from] if edge[:relation] == :dependency
+  end
+  ordered_jobs = []
+  visited_jobs = Set.new
+  visit_job = lambda do |key|
+    next if visited_jobs.include?(key)
+    visited_jobs << key
+    predecessors[key].sort_by(&:last).each { |dep| visit_job.call(dep) }
+    ordered_jobs << key
+  end
+  job_keys.sort_by(&:last).each { |key| visit_job.call(key) }
+  chat_keys = (visible_keys - job_keys).sort_by(&:last)
+  ordered_keys = ordered_jobs + chat_keys
+  indexes = ordered_keys.each_with_index.to_h { |key, index| [key, index + 1] }
+
+  def short_number(number)
+    number = number.to_i
+    return format('%.1fM', number / 1_000_000.0) if number >= 1_000_000
+    return format('%.1fk', number / 1_000.0) if number >= 1_000
+    number.to_s
+  end
+
+  if flow
+    puts 'Flow'
+    puts '===='
+    ordered_keys.each do |key|
+      node = nodes[key]
+      name = node_label(node, nil, nil, key, long)
+      tokens = short_number(node_tokens.call(key)[:tt])
+      id = node[:kind] == :job ? job_short_id(node[:path]) : Misc.digest(node[:path])[0, 8]
+      puts format('[%2d] %-5s %-52s %8s %s', indexes[key], node[:kind].to_s.capitalize, name, tokens, id)
+    end
+    puts
+    flow_edges.each do |edge|
+      next unless visible_set.include?(edge[:from]) && visible_set.include?(edge[:to])
+      puts format('[%2d] --%-10s--> [%2d]', indexes[edge[:from]], edge[:relation], indexes[edge[:to]])
+    end
+  end
+
+  if dot_file || plot_file
+    ids = ordered_keys.each_with_index.to_h { |key, index| [key, "n#{index}"] }
+    lines = [
+      'digraph scout_ai_provenance {',
+      '  graph [rankdir=LR, bgcolor="white", pad=0.2, nodesep=0.35, ranksep=0.6];',
+      '  node [fontname="Helvetica", fontsize=10];',
+      '  edge [fontname="Helvetica", fontsize=8, arrowsize=0.7];'
+    ]
+    ordered_keys.each do |key|
+      node = nodes[key]
+      label = "#{node[:kind].to_s.capitalize}\n#{node_label(node, nil, nil, key, long)}\n#{short_number(node_tokens.call(key)[:tt])} tokens"
+      shape = node[:kind] == :job ? 'box' : 'note'
+      lines << %(  #{ids[key]} [shape=#{shape}, style="rounded,filled", fillcolor="#f7f7f7", label=#{JSON.generate(label)}];)
+    end
+    styles = {
+      result: 'color="#39804a", penwidth=1.5, label="result"',
+      delegated_result: 'color="#8a6d3b", penwidth=1.2, label="delegated_result"',
+      dependency: 'color="#333333", label="dependency"',
+      log: 'color="#2864a5", style="dashed", label="log"'
+    }
+    flow_edges.each do |edge|
+      next unless visible_set.include?(edge[:from]) && visible_set.include?(edge[:to])
+      lines << %(  #{ids[edge[:from]]} -> #{ids[edge[:to]]} [#{styles[edge[:relation]] || "label=#{JSON.generate(edge[:relation].to_s)}"}];)
+    end
+    lines << '}'
+    dot = lines * "\n"
+    Open.write(dot_file, dot) if dot_file
+
+    if plot_file
+      extension = File.extname(plot_file).sub(/^\./, '').downcase
+      extension = 'svg' if extension.empty?
+      raise ParameterException, "Unsupported plot format: #{extension}" unless %w[svg png pdf].include?(extension)
+      Tempfile.create(['scout-ai-provenance', '.dot']) do |file|
+        file.write(dot)
+        file.flush
+        raise ScoutException, 'Graphviz dot failed' unless system('dot', "-T#{extension}", file.path, '-o', plot_file.to_s)
+      end
+    end
+  end
+end
+
+# ------------------------------------------------------------------
+# Evidence mode: the deduplicated direct inference events behind the totals
+# ------------------------------------------------------------------
+if evidence
+  def evidence_location_str(address)
+    return '' unless Array === address && address.any?
+    rest = address[1..-1]
+    base = address[0].nil? ? '?' : File.basename(address[0].to_s)
+    if rest.length >= 3 && (rest[1] == :agent_meta || rest[1] == :meta)
+      "#{base}:#{rest[0]}[#{rest[1]},#{rest[2]}]"
+    else
+      "#{base}:#{rest[0]}"
+    end
+  end
+
+  def event_id_str(event)
+    return event[:inference_id] if event[:inference_id]
+    identity = event[:identity]
+    # Legacy receipts have no stable id: show the receipt location instead of
+    # the raw address array.
+    return "receipt=#{evidence_location_str(identity[1])}" if identity.first == :receipt
+    identity.length == 2 ? "#{identity[0]}=#{identity[1]}" : identity * '='
+  end
+
+  def event_status(event)
+    if event[:conflict]
+      'conflict (counted once, not authoritative)'
+    elsif event[:incomplete_evidence]
+      'incomplete evidence'
+    elsif event[:deduplication] == :receipt_unresolved
+      'legacy unresolved'
+    elsif event[:evidence].all? { |item| item[:origin] == :agent_meta }
+      'receipt-only'
+    else
+      'counted once'
+    end
+  end
+
+  events = token_events_for.call
+  puts
+  puts 'Direct inference events'
+  puts '======================='
+  if events.empty?
+    puts '(none)'
+  else
+    # Raw integers here: every number must stay directly comparable with the
+    # meta records at the evidence addresses.
+    rows = events.collect do |event|
+      tokens = event[:tokens]
+      token_parts = ["total=#{tokens[:tt].to_i}"]
+      token_parts << "prompt=#{tokens[:pt].to_i}" if tokens[:pt].to_i > 0
+      token_parts << "cont=#{tokens[:ct].to_i}" if tokens[:ct].to_i > 0
+      token_parts << "cache=#{tokens[:cct].to_i}" if tokens[:cct].to_i > 0
+      token_parts << "reason=#{tokens[:rt].to_i}" if tokens[:rt].to_i > 0
+      evidence_parts = event[:evidence].collect do |item|
+        location = evidence_location_str(item[:evidence_address] || item[:meta_address])
+        call = item[:call_id] ? " call=#{item[:call_id]}" : ''
+        "#{item[:origin]} #{location}#{call}"
+      end
+      [event_id_str(event), token_parts * ' ', evidence_parts * '; ', event_status(event)]
+    end
+    puts format('%-26s %-36s %-56s %s', 'Inference ID', 'Tokens', 'Evidence', 'Status')
+    rows.each { |row| puts format('%-26s %-36s %-56s %s', *row) }
+  end
+
+  receipt_only = events.select { |event| event_status(event) == 'receipt-only' }
+  legacy_unresolved = events.select { |event| event[:deduplication] == :receipt_unresolved }
+
+  unless receipt_only.empty?
+    puts
+    puts "Receipt-only events (no saved child log): #{receipt_only.collect { |event| event_id_str(event) } * ', '}"
+  end
+
+  unless legacy_unresolved.empty?
+    puts
+    puts 'Legacy unresolved events (no inference_id; one per receipt, may overcount):'
+    legacy_unresolved.each do |event|
+      location = evidence_location_str(event[:evidence].first[:evidence_address])
+      puts "  #{event_id_str(event)} at #{location}"
+    end
+  end
+
+  seen_conflicts = Set.new
+  conflicts = receipt_warnings.select do |warning|
+    warning[:reason] == :identity_conflict && seen_conflicts.add?(warning[:identity])
+  end
+  unless conflicts.empty?
+    puts
+    puts 'Identity conflicts (counted once from canonical evidence; totals containing these are NOT authoritative):'
+    conflicts.each do |conflict|
+      values = conflict[:values].collect { |field, list| "#{field}=#{Array(list).uniq * '|'}" } * ' '
+      puts "  #{conflict[:identity] * '='}: disputed #{conflict[:fields] * ','} (#{values})"
+    end
+  end
+
+  incomplete = events.select { |event| event[:incomplete_evidence] }
+  unless incomplete.empty?
+    puts
+    puts 'Incomplete evidence (one copy lacks provider_response_id; no conflict):'
+    incomplete.each do |event|
+      puts "  #{event_id_str(event)}"
+    end
+  end
+
+  # Agent-job references come straight from the traversal edge details, so no
+  # parent chat has to be re-parsed here: the edge already carries the receipt
+  # record (call id, tool name, output address, receipt address, reference).
+  agent_job_edges = records.select do |kind, _object, parent_kind, _parent, relation, _first|
+    relation == :agent_job && parent_kind == :chat && kind == :job
+  end
+  unless agent_job_edges.empty?
+    puts
+    puts 'Job projection references (no direct tokens):'
+    agent_job_edges.each do |_kind, object, _parent_kind, _parent, _relation, _first, detail|
+      detail ||= {}
+      location = evidence_location_str(detail[:evidence_address])
+      tool = detail[:tool_name] || '?'
+      puts "  job=#{object.path} at #{location} call=#{detail[:call_id]} tool=#{tool} (delegated_result edge)"
+    end
+  end
+end
+
+warnings.each do |warning|
+  error = warning[:error]
+  # Receipt problems are reported in detail by the receipt_warnings block
+  # below (reason, location, call id); skip the generic line for them.  They
+  # are recognized by their structured reference, not by a class: agent_meta
+  # diagnostics travel as ordinary ScoutException plus a reference Hash.
+  next if warning[:relation] == :agent_job && Hash === warning[:reference] && warning[:reference][:reason]
+  Log.warn "Incomplete provenance at #{warning[:kind]} #{warning[:object]} (#{warning[:relation]}): #{error.message}"
+end
+
+# Receipt problems and identity conflicts collected by the token collector.
+# The same problem may be reported once per aggregate subtree, so printed
+# lines are deduplicated by their location.
+seen_receipt_warnings = Set.new
+receipt_warnings.each do |warning|
+  key = warning.values_at(:reason, :source, :output_address, :call_id, :agent_meta_index, :identity)
+  next unless seen_receipt_warnings.add?(key)
+  if warning[:reason] == :identity_conflict
+    Log.warn "identity conflict: #{warning[:identity] * '='} disagrees on #{warning[:fields] * ','}"
+  else
+    location = warning[:evidence_address] || warning[:output_address]
+    Log.warn "agent_meta receipt: #{warning[:reason]} in #{warning[:source]} at #{location.inspect} call=#{warning[:call_id]}#{warning[:message] ? ' - ' + warning[:message] : ''}"
+  end
+end

data/scout_commands/llm/word

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'scout'
+
+cmd = $previous_commands ?
+  "scout #{$previous_commands.any? ? "#{$previous_commands * ' '} " : ''}#{File.basename(__FILE__)}" :
+  $PROGRAM_NAME
+
+options = SOPT.setup <<~EOF
+
+Format a chat in word
+
+$ #{cmd} [<options>] <chat> <word>
+
+-h--help Print this help
+-r--reference* Use a different reference.docx
+-l--last Format only the last interaction
+EOF
+if options[:help]
+  if defined? scout_usage
+    scout_usage
+  else
+    puts SOPT.doc
+  end
+  exit 0
+end
+
+help, reference, last = IndiferentHash.process_options options, :help, :reference, :last
+
+reference ||= Scout.share.word["reference.docx"].find
+
+chat, word, _ = ARGV
+
+raise MissingParameterException, :chat if chat.nil?
+
+if word.nil?
+  word = chat.sub(/\.(txt|chat|md)$/i, '') + '.docx'
+end
+
+messages = Chat.parse Open.read(chat)
+
+if last
+  messages = messages.select{|m| %w(user assistant).include? m[:role].to_s }[-2..-1]
+end
+
+out = [] 
+messages.each do |message|
+  IndiferentHash.setup(message)
+  case message['role']
+  when 'user'
+    out.push <<-EOF
+
+::: {custom-style="UserBlock"}
+
+#{message['content']}
+
+:::
+
+    EOF
+  when 'assistant'
+    out.push message['content']
+  else
+    next
+  end
+end
+
+TmpFile.with_file out * "\n", extension: :md do |markdown|
+  CMD.cmd(:pandoc, "'#{markdown}' --reference-doc=#{reference} -o #{word}")
+end
+puts word