samagotchi 0.15.0 → 0.16.0

data/lib/samagotchi/relay_verifier.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "bridge_client"
+require_relative "worker_sidecar"
+require_relative "question_desk"
+require_relative "guardrails/parent_approvals"
+require_relative "log"
+
+module Samagotchi
+  # A child worker taking its parent's answer to a relayed approval. The
+  # POST that says "answered" carries no answer and no authority: this
+  # worker asks its parent session's live Bridge what the parent's relay
+  # holds (RelayDesk, which only the parent's question flow writes), and
+  # answers its own question with that, only when it is about this session
+  # and the question pending now, and is answered.
+  class RelayVerifier
+    # The client id a relayed answer is recorded with: relay:<parent8>.
+    CLIENT_PREFIX = "relay"
+
+    # @param engine [Engine] this (the child's) worker's Engine
+    def initialize(engine:, state_dir:, session_id:)
+      @engine = engine
+      @state_dir = state_dir
+      @session_id = session_id
+    end
+
+    # @return [Array(Hash, Integer, Hash)] headers, status, body: 200
+    #   answered, 409 no longer pending, 403 refused (a parent agent's allow
+    #   beyond this worker's guardrails.parent_approvals), 422
+    #   relay_unverified (logged; the question stays open)
+    def answer(relay_id:, question_id:)
+      parent_id = own_parent_id or return unverified("this session has no parent", relay_id)
+      relay = parent_relay(parent_id, relay_id) or return unverified("the parent has no such relay", relay_id)
+      return unverified("the relay is about another session", relay_id) unless relay["child_id"] == @session_id
+      return unverified("the relay is about another question", relay_id) unless relay["child_question_id"] == question_id
+      return unverified("the relay is #{relay["state"]}, not answered", relay_id) unless relay["state"] == "answered"
+
+      apply(relay, parent_id: parent_id, question_id: question_id, relay_id: relay_id)
+    end
+
+    private
+
+    def apply(relay, parent_id:, question_id:, relay_id:)
+      answer = relay["answer"].is_a?(Hash) ? relay["answer"] : {}
+      parent_agent = relay["by"] != "user"
+      client_id = "#{CLIENT_PREFIX}:#{parent_id[0, 8]}"
+      if answer["dismissed"]
+        return not_pending(question_id) unless @engine.cancel_question("dismissed", id: question_id)
+
+        log("relay_answered", relay_id, id: question_id, dismissed: true, by: relay["by"])
+        return [{}, 200, { status: "dismissed", question_id: question_id }]
+      end
+
+      selected = labels(answer["selected_indices"], question_id) or return unverified("the answer's option is out of range", relay_id)
+      result = @engine.answer_question(id: question_id, selected: selected, freeform: answer["freeform"],
+                                       client_id: client_id, parent_agent: parent_agent)
+      log("relay_answered", relay_id, id: question_id, by: relay["by"])
+      [{}, 200, { status: "answered", question_id: question_id, answer: result }]
+    rescue QuestionDesk::NotPending
+      not_pending(question_id)
+    rescue QuestionDesk::Refused => e
+      log("relay_refused", relay_id, id: question_id, reason: e.reason)
+      [{}, 403, { error: "parent_approval_refused", reason: e.reason.to_s,
+                  detail: Guardrails::ParentApprovals.message(e.reason) }]
+    rescue ArgumentError => e
+      unverified("the answer doesn't fit the question: #{e.message}", relay_id)
+    end
+
+    # The parent's option indices as this question's own labels (the
+    # parent's are relabelled; the order is the same). nil when one is out
+    # of range; [] for a freeform-only deny.
+    def labels(indices, question_id)
+      pending = @engine.pending_question
+      return [] unless pending && pending[:id].to_s == question_id
+
+      options = Array(pending[:options])
+      indices = Array(indices)
+      return nil unless indices.all? { |index| index.is_a?(Integer) && index >= 0 && index < options.size }
+
+      indices.map { |index| options[index] }
+    end
+
+    def own_parent_id
+      Session.load(@session_id, state_dir: @state_dir).parent_id
+    rescue ArgumentError
+      nil
+    end
+
+    # @return [Hash, nil] what the parent's live Bridge says about the relay
+    def parent_relay(parent_id, relay_id)
+      dir = Session.session_dir(parent_id, state_dir: @state_dir)
+      client = BridgeClient.discover(parent_id, session_dir: dir) or return nil
+      response = client.relay_status(relay_id)
+      response.ok? ? response.json : nil
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    def not_pending(question_id)
+      [{}, 409, { error: "question_not_pending", detail: "no pending question #{question_id}" }]
+    end
+
+    def unverified(why, relay_id)
+      log("relay_unverified", relay_id, why: why)
+      [{}, 422, { error: "relay_unverified", detail: why }]
+    end
+
+    def log(event, relay_id, **fields)
+      Log.info(:bridge, event, sid: @session_id, relay: relay_id.to_s[0, 8], **fields)
+    end
+  end
+end

data/lib/samagotchi/relay_watcher.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "worker_sidecar"
+require_relative "log"
+
+module Samagotchi
+  # A child's look at its parent while its question is relayed there: when
+  # the parent's worker is gone, its relay card and RelayDesk went with it,
+  # so the question's relay mark is cleared (reason parent_gone) and its
+  # cards say "answer here" again. Outside the question desk: it clears a
+  # mark, never cancels the question. Stops once the question is no longer
+  # that relay's.
+  module RelayWatcher
+    INTERVAL = 2
+
+    module_function
+
+    # @param engine [Engine] the child's
+    # @param parent_dir [String] the parent session's folder (its sidecar)
+    # @param live [#call] whether the parent's worker is up
+    # @return [Thread]
+    def start(engine:, question_id:, relay_id:, parent_dir:, interval: INTERVAL,
+              live: -> { WorkerSidecar.live(parent_dir, unlink: false) })
+      Thread.new do
+        loop do
+          sleep(interval)
+          break unless relayed?(engine.pending_question, question_id, relay_id)
+          next if live.call
+
+          Log.info(:bridge, "relay_parent_gone", id: question_id)
+          engine.annotate_question(question_id, relayed_to: nil, reason: "parent_gone")
+          break
+        end
+      rescue StandardError => e
+        Log.warn(:bridge, "relay_watch_failed", error: e.class.name, message: e.message)
+      end.tap { |thread| thread.report_on_exception = false }
+    end
+
+    def relayed?(pending, question_id, relay_id)
+      relay = pending && pending[:relayed_to]
+      return false unless relay.is_a?(Hash) && pending[:id].to_s == question_id.to_s
+
+      (relay[:relay_id] || relay["relay_id"]).to_s == relay_id.to_s
+    end
+  end
+end

data/lib/samagotchi/reply_wait.rb

@@ -50,10 +50,13 @@ module Samagotchi
     #   a failure replaces the note and leaves the count as it was.
     # @param owner_grace [Numeric, nil] seconds with no live worker before
     #   :worker_gone (one that died before its rescue leaves it running)
+    # @param interject [#call, nil] called once a poll, before the sleep
+    #   (the delegate wait relays other children's approvals there); the
+    #   time it takes doesn't count against +timeout+
     # @return [Result]
     # @raise [ArgumentError] no such session
     def call(id, state_dir:, cursor:, timeout: nil, poll_interval: POLL_INTERVAL, cancelled: -> { false },
-             baseline: nil, owner_grace: nil)
+             baseline: nil, owner_grace: nil, interject: nil)
       deadline = timeout && (monotonic + timeout.to_f)
       seen_running = false
       gone_since = nil
@@ -104,6 +107,12 @@ module Samagotchi
 
         return Result.new(status: :timeout) if deadline && monotonic > deadline
 
+        if interject
+          started = monotonic
+          interject.call
+          deadline += monotonic - started if deadline
+          next if cancelled.call
+        end
         sleep(poll_interval)
       end
     end

data/lib/samagotchi/session.rb

@@ -111,7 +111,9 @@ module Samagotchi
       return nil unless live && pending.is_a?(Hash) && pending[:id]
 
       kind = pending[:kind].to_s
-      { id: pending[:id], kind: %w[approval hook].include?(kind) ? kind : "question" }
+      relayed = pending[:relayed_to]
+      relayed_to = relayed.is_a?(Hash) ? (relayed[:parent_short] || relayed["parent_short"]) : nil
+      { id: pending[:id], kind: %w[approval hook].include?(kind) ? kind : "question", relayed_to: relayed_to }.compact
     end
 
     # The stored project root, else (a file from before the field) the
@@ -464,7 +466,18 @@ module Samagotchi
             entry.is_a?(Hash) ? entry.each_with_object({}) { |(k, v), h| h[k.to_sym] = v } : entry
           end
         end
-        message
+        symbolize_empty_answer(message)
+      end
+
+      # An empty-answer note's marker (TurnNote.empty) and its steps, as
+      # they were saved.
+      def symbolize_empty_answer(message)
+        marker = message[:empty_answer]
+        return message unless marker.is_a?(Hash)
+
+        marker = marker.transform_keys(&:to_sym)
+        marker[:steps] = marker[:steps].map { |step| step.is_a?(Hash) ? step.transform_keys(&:to_sym) : step } if marker[:steps].is_a?(Array)
+        message.merge(empty_answer: marker)
       end
 
       def session_path(session_id, state_dir:)

data/lib/samagotchi/session_manager.rb

@@ -241,7 +241,8 @@ module Samagotchi
     #   a turn running, recap = the saved recap's first sentence, project =
     #   Session#project_root, waiting = the kind of question it waits on
     #   ("question", "approval", "hook"; Session#waiting_question) or nil,
-    #   waiting_id = that question's id or nil
+    #   waiting_id = that question's id or nil, relayed_to = the parent
+    #   whose card it waits in too (the approval relay), its short id, or nil
     def self.session_summaries(live: false, cwd: nil, limit: nil, include_tests: true, exclude: nil, state_dir: nil,
                                project_root: nil, include_archived: false, sort: nil, order: nil)
       sd = state_dir || Session.default_state_dir
@@ -269,7 +270,7 @@ module Samagotchi
     # waiting: the question's kind, waiting_id: its id (what chi answer
     # --question takes); both nil with none.
     def self.waiting_fields(waiting)
-      { waiting: waiting&.dig(:kind), waiting_id: waiting&.dig(:id) }
+      { waiting: waiting&.dig(:kind), waiting_id: waiting&.dig(:id), relayed_to: waiting&.dig(:relayed_to) }
     end
     private_class_method :waiting_fields
 

data/lib/samagotchi/session_metrics.rb

@@ -83,6 +83,23 @@ module Samagotchi
       nil
     end
 
+    # One turn's tool records from the session's saved analytics.json, in
+    # call order (iteration, then call_index), string-keyed as saved: what a
+    # join replays the turn's tool rows' durations from. Empty without a turn
+    # id (an older session's prompt), the file, or records.
+    # @param session_dir [String]
+    # @param turn_id [String, nil]
+    # @return [Array<Hash>]
+    def self.saved_tool_records(session_dir, turn_id)
+      return [] if turn_id.to_s.empty?
+
+      records = JSON.parse(File.read(File.join(session_dir, "analytics.json")))["tool_records"]
+      Array(records).select { |r| r.is_a?(Hash) && r["turn_id"] == turn_id }
+                    .sort_by { |r| [r["iteration"].to_i, r["call_index"].to_i] }
+    rescue JSON::ParserError, SystemCallError, TypeError
+      []
+    end
+
     # "ctx 12%" for the session lists, "" when unknown.
     # @param pct [Float, nil]
     # @return [String]

data/lib/samagotchi/sessions_command.rb

@@ -148,15 +148,17 @@ module Samagotchi
         # ctx_pct: how full the context was after the last turn, or nil
         # waiting: the kind of question it waits on (question, approval,
         # hook: chi answer or the web answers it), or nil; waiting_id: its
-        # id, for chi answer --question
+        # id, for chi answer --question; relayed_to: the parent session (short
+        # id) whose card it also waits in (the approval relay), or nil
         keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id archived scratch ctx_pct waiting
-                  waiting_id]
+                  waiting_id relayed_to]
         @stdout.puts JSON.generate(summaries.map { |summary| summary.slice(*keys) })
       when "tsv"
         summaries.each { |summary| @stdout.puts "#{summary[:id]}\t#{summary[:desc]}" }
       else
         summaries.each do |summary|
-          state = if summary[:waiting] then "waiting"
+          state = if summary[:relayed_to] then "waiting (in parent #{summary[:relayed_to]})"
+                  elsif summary[:waiting] then "waiting"
                   elsif summary[:busy] then "running"
                   else summary[:live] ? "live" : summary[:status].to_s
                   end
@@ -206,7 +208,11 @@ module Samagotchi
         )
         # A question waits for an answer (chi answer, the web, chi --attach).
         live = s.pending_question && Samagotchi::SessionManager.worker_live?(s.id, state_dir: state_dir)
-        status = s.waiting_question(live: !!live) ? "waiting" : s.status
+        waiting = s.waiting_question(live: !!live)
+        status = if waiting&.dig(:relayed_to) then "waiting (in parent #{waiting[:relayed_to]})"
+                 elsif waiting then "waiting"
+                 else s.status
+                 end
         "#{s.id}  #{status.ljust(8)}  #{ctx.ljust(8)}  #{s.updated_at}  #{list_text.call(s)}#{flag}#{child}"
       end
       if project

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -38,7 +38,7 @@ module Samagotchi
       # @param muted_memories [Array<String>] --mute: hidden from a new session
       # @return [Symbol] :detached, :closed when the worker went away,
       #   :failed when the --model switch didn't go through, or (input from a
-      #   pipe) :turn_failed / :unanswered (AttachedLoop#run)
+      #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
               memories: [], muted_memories: [])
         client = connect(attach: attach, shared: shared, resume: resume, model: model,
@@ -56,6 +56,7 @@ module Samagotchi
           close_surface(surface)
         end
         report_unanswered(attached.unanswered, session_id: client.session_id) if ended == :unanswered && attached.unanswered
+        report_ended(ended)
         ended
       end
 
@@ -68,9 +69,17 @@ module Samagotchi
         err.flush
       end
 
+      # A turn of ours that ended with no answer (input from a pipe): one
+      # line on stderr, as the in-process `chi -p --non-interactive` says
+      # it, so a script doesn't take the silence for an answer (exit 1).
+      def report_ended(ended, err: $stderr)
+        err.puts(TerminalUI::EMPTY_ANSWER_ERROR) if ended == :empty_answer
+      end
+
       # chi's exit status after #run: 0 detached, 3 a question left waiting
       # for an answer (input from a pipe ran out; chi --attach or chi answer
-      # answers it), 1 anything else (a failed turn, the worker gone).
+      # answers it), 1 anything else (a failed turn, an empty answer, the
+      # worker gone).
       # @param ended [Symbol] what #run returned
       # @return [Integer]
       def exit_status(ended)

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -20,6 +20,7 @@ require_relative "../model_profile"
 require_relative "../output_formatter"
 require_relative "../session_commands"
 require_relative "../session_manager"
+require_relative "../session_metrics"
 require_relative "../guardrails/parent_approvals"
 require_relative "../tool_activity"
 require_relative "../web/message_parts"
@@ -143,8 +144,9 @@ module Samagotchi
       # asks it to exit too, and it does unless something still needs it.
       # @return [Symbol] :detached, :closed when the worker went away,
       #   :failed when the first command (--model) didn't go through, or
-      #   (wait_at_eof) :turn_failed when one of this run's prompts failed and
-      #   :unanswered when a question came after the input ended
+      #   (wait_at_eof) :turn_failed when one of this run's prompts failed,
+      #   :empty_answer when one ended with no answer, and :unanswered when
+      #   a question came after the input ended
       # @param input [#call, nil] prompt -> line (nil = Ctrl-D, raising
       #   Interrupt = Ctrl-C); defaults to Reline
       def run(input: nil)
@@ -259,7 +261,9 @@ module Samagotchi
           ask(event[:pending_question])
         when :question_answered then question_answered(event)
         when :question_cancelled
-          close_question("(question cancelled)") if @question
+          close_question(@question.closed_text(event[:reason])) if @question
+        # Relayed to the parent's card, or no longer: the widget says so.
+        when :question_relay then question_relayed(event)
         # Written while the session sat idle: shown at the open prompt. One
         # collected just as a turn started describes the chat before it.
         when :recap_ready then @screen.commit(recap_block(event[:recap])) unless @running || event[:recap].to_s.strip.empty?
@@ -569,6 +573,7 @@ module Samagotchi
         id = (event[:origin] || {})[:enqueued_id]
         ours = @open_ids.include?(id) || !@merged_ids.empty?
         @own_failed = true if ours && event[:type] == :turn_failed
+        @own_empty = true if ours && event[:type] == :turn_completed && event.dig(:turn_summary, :empty_answer)
         @open_ids.delete(id)
         @open_ids.subtract(@merged_ids)
         @merged_ids.clear
@@ -591,7 +596,9 @@ module Samagotchi
       # The input ended and nothing of ours is left to wait for.
       def end_of_input
         detach("Detached; the session keeps running. Re-attach with: chi --attach #{@client.session_id}") if @input_ended
-        @own_failed ? :turn_failed : :detached
+        return :turn_failed if @own_failed
+
+        @own_empty ? :empty_answer : :detached
       end
 
       def unanswered_question(pending)
@@ -757,6 +764,13 @@ module Samagotchi
         end
       end
 
+      def question_relayed(event)
+        return unless @question && @question.id == event[:id].to_s
+
+        @question.relayed_to = event[:relayed_to]
+        @screen.set_slot(:notes, @question.slot(paint: method(:paint)))
+      end
+
       def question_answered(event)
         return unless @question
         return close_question(nil) if @answered_ids.include?(event[:id])
@@ -939,39 +953,76 @@ module Samagotchi
 
         @screen.commit(prompt_line(nil, exchange[last_user][:content]))
         Array(exchange[last_user][:images]).each { |ref| @screen.commit(format_image_line(ref)) }
-        render_join_steps(messages, messages.index { |m| m.equal?(exchange[last_user]) })
-        # The saved answer is raw: the latest keeps its thinking, and one may
-        # be only a tool call.
-        answer = exchange[(last_user + 1)..].reverse_each
-                                           .map { |m| OutputFormatter.strip_markup(m[:content]) }
-                                           .find { |text| !text.empty? }
-        @screen.commit(last_lines(answer)) if answer
+        from = messages.index { |m| m.equal?(exchange[last_user]) }
+        render_join_steps(messages, from, durations: join_tool_records(exchange[last_user]))
+        # A turn that ended with no answer: its notice, as live.
+        empty = messages.drop(from + 1).filter_map { |m| TurnNote.empty_answer(m) }.last
+        if empty
+          @screen.commit(format_empty_answer_line(empty[:retries] || empty["retries"]))
+        else
+          # The saved answer is raw: the latest keeps its thinking, and one may
+          # be only a tool call.
+          answer = exchange[(last_user + 1)..].reverse_each
+                                             .map { |m| OutputFormatter.strip_markup(m[:content]) }
+                                             .find { |text| !text.empty? }
+          @screen.commit(last_lines(answer)) if answer
+        end
         render_join_notes(messages, after_exchange: true)
       end
 
       # What the last exchange did, as the live turn drew it: each saved
-      # call's tool row (action, params, status from its result; no
-      # duration, which the session doesn't keep) and a plugin's steer
-      # where it came. The step texts stay out, as live (the ticker's).
-      def render_join_steps(messages, from)
+      # call's tool row (action, params, status from its result, and its
+      # duration from +durations+, the turn's saved tool records) and a
+      # plugin's steer where it came. The step texts stay out, as live (the
+      # ticker's).
+      def render_join_steps(messages, from, durations: [])
+        records = durations.dup
         messages.each_with_index.drop(from + 1).each do |m, i|
           if Steer.steer?(m)
             @screen.commit(format_steer_line(source: m[:source], text: m[:content]))
           elsif %w[model assistant].include?(m[:role].to_s)
             responses = messages.drop(i + 1).take_while { |r| r[:role].to_s == "tool_response" }
-            Array(Web::MessageParts.for_message(m, responses)&.dig(:tools)).each { |part| @screen.commit(join_tool_line(part)) }
+            Array(Web::MessageParts.for_message(m, responses)&.dig(:tools)).each do |part|
+              @screen.commit(join_tool_line(part, duration_ms: join_duration(records, part)))
+            end
           end
         end
       end
 
+      # The prompt's turn's saved tool records (SessionMetrics, in this
+      # machine's state dir, as #attach_images): none for a prompt with no
+      # turn id (an older session) or a session with no analytics.
+      def join_tool_records(prompt)
+        SessionMetrics.saved_tool_records(Session.session_dir(@client.session_id), prompt[:turn_id] || prompt["turn_id"])
+      rescue Session::InvalidId
+        []
+      end
+
+      # The duration of +part+'s call: the next record of its tool, in call
+      # order, consumed with the ones it skipped. By tool and order, not by
+      # iteration: an empty retry spends an iteration that left no message.
+      # nil (no duration shown) for a call that left none: it never
+      # finished, or a worker before turn ids saved it.
+      def join_duration(records, part)
+        return nil if part[:output].nil?
+
+        at = records.index { |r| r["tool"].to_s == part[:tool].to_s }
+        return nil unless at
+
+        duration = records[at]["duration_ms"]
+        records.shift(at + 1)
+        duration.is_a?(Numeric) ? duration : nil
+      end
+
       # A saved call's row; "no result" for a call the turn never answered
       # (it ended first).
-      def join_tool_line(part)
+      def join_tool_line(part, duration_ms: nil)
         output = part[:output]
         status = output.nil? ? "no result" : ToolActivity.tool_activity_status(output, part[:tool])
         activity = { action: part[:label] || ToolActivity.tool_activity_action(part[:tool]), tool: part[:tool],
                      params: part[:params], status: status }
-        "#{format_tool_activity_line(activity)}#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}"
+        "#{format_tool_activity_line(activity, duration_ms: duration_ms)}" \
+          "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}"
       end
 
       # The context notes that came since the last prompt (all of them in a

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -167,7 +167,12 @@ module Samagotchi
 
           @view.print_line(@view.format_tool_activity_line(activity))
         end
-        @view.print_line(summary[:output])
+        # No answer: chi's muted notice, never an empty answer line.
+        if summary[:empty_answer]
+          @view.print_line(@view.format_empty_answer_line(summary.dig(:empty_answer, :retries)))
+        else
+          @view.print_line(summary[:output])
+        end
         @view.print_line("iteration limit reached") if summary[:resumable]
       end
 

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -2,6 +2,7 @@
 
 require_relative "../served_model"
 require_relative "../image_store"
+require_relative "../turn_note"
 
 module Samagotchi
   class TerminalUI
@@ -44,6 +45,12 @@ module Samagotchi
         paint("↻ #{what}, asking again (#{event[:attempt]}/#{event[:of]})", 90)
       end
 
+      # "no answer: the model returned nothing (after 1 retry)", dim like the
+      # retry row: a turn that ended with no answer (TurnNote.empty_answer_line).
+      def format_empty_answer_line(retries)
+        paint(TurnNote.empty_answer_line(retries), 90)
+      end
+
       # "retrying (1/3 in 0.5s): Errno::ECONNREFUSED": the retry of all the
       # retries there will be (as the web counts), the wait before it, and
       # what failed (generation_retrying).

data/lib/samagotchi/terminal_ui/question_prompt.rb

@@ -22,6 +22,9 @@ module Samagotchi
       end
 
       attr_reader :id, :question, :options, :header
+      # @return [String, nil] the parent's short id while this question waits
+      #   in its card too (the approval relay)
+      attr_reader :relayed_to
 
       # @param pending [Hash] Engine#pending_question (symbol or string keys)
       def initialize(pending)
@@ -30,6 +33,18 @@ module Samagotchi
         @preview = approval.is_a?(Hash) ? (approval[:preview] || approval["preview"]) : nil
         @id = field.(:id).to_s
         @question = field.(:question).to_s
+        # A delegate's approval relayed here: the delegate's own text is the
+        # question, who asks a dim line (#note).
+        relay = field.(:relay)
+        if relay.is_a?(Hash)
+          get = ->(key) { relay[key] || relay[key.to_s] }
+          chain = Array(get.(:chain)).map(&:to_s)
+          chain = [get.(:child_id).to_s[0, 8]] if chain.empty?
+          @delegate = chain.reverse.join(" → ")
+          @delegate_task = get.(:task).to_s
+          @question = get.(:asked).to_s unless get.(:asked).to_s.strip.empty?
+        end
+        self.relayed_to = field.(:relayed_to)
         @options = Array(field.(:options)).map { |v| v.to_s.strip }.reject(&:empty?)
         header = field.(:header).to_s.strip
         @header = header.empty? ? nil : header
@@ -42,6 +57,36 @@ module Samagotchi
       def free? = @free
       def approval? = @approval
 
+      # The relay mark (QuestionDesk#annotate's relayed_to: a Hash, or the
+      # short id), or nil when cleared.
+      def relayed_to=(value)
+        short = value.is_a?(Hash) ? (value[:parent_short] || value["parent_short"]) : value
+        @relayed_to = short.to_s.strip.empty? ? nil : short.to_s
+      end
+
+      # The dim line under the header: which delegate asks (and its task),
+      # or that this question waits in a parent too.
+      def note
+        if @delegate
+          task = @delegate_task.empty? ? "" : " · #{@delegate_task}"
+          return "  delegate #{@delegate}#{task}"
+        end
+        "  waiting in parent #{@relayed_to} too (answering here works)" if @relayed_to
+      end
+
+      # What a question closed with no answer here says: a relayed approval
+      # names where it went; else "(question cancelled)".
+      def closed_text(reason)
+        return "(question cancelled)" unless @delegate
+
+        case reason.to_s
+        when "answered_on_child" then "(answered in #{@delegate})"
+        when "child_gone" then "(#{@delegate}'s worker is gone)"
+        when "dismissed" then "(denied)"
+        else "(left open in #{@delegate})"
+        end
+      end
+
       # The widget as slot content, fitted to the rows it gets (QuestionSlot).
       # @return [QuestionSlot]
       def slot(paint: ->(text, _code) { text })
@@ -50,7 +95,7 @@ module Samagotchi
         QuestionSlot.new(header: approval? ? (header || "Approve tool call?") : header,
                          question: first.to_s, mark: mark, details: rest,
                          options: keys.zip(options).map { |key, label| QuestionSlot::Option.new(key, label) },
-                         hint: slot_hint, question_code: approval? ? 33 : 94, paint: paint)
+                         hint: slot_hint, question_code: approval? ? 33 : 94, paint: paint, note: note)
       end
 
       # The most diff lines #preview_lines prints; the web shows them all.
@@ -85,7 +130,8 @@ module Samagotchi
       # the question and what became of it.
       # @param outcome [String] the answer (#answer_text) or what closed it
       def summary(outcome, paint: ->(text, _code) { text })
-        "#{paint.("#{mark}#{question.lines.first.to_s.chomp}", approval? ? 33 : 94)} → #{outcome}"
+        who = @delegate ? "#{@delegate}: " : ""
+        "#{paint.("#{mark}#{who}#{question.lines.first.to_s.chomp}", approval? ? 33 : 94)} → #{outcome}"
       end
 
       # @param answer [Answer] an accepted one

data/lib/samagotchi/terminal_ui/question_slot.rb

@@ -38,9 +38,12 @@ module Samagotchi
       # @param mark [String] its prefix ("? ", "! ")
       # @param options [Array<Option>] key ("1", "yes") and label
       # @param paint [#call] (text, code) -> coloured text
+      # @param note [String, nil] a dim row under the header (a relayed
+      #   approval's delegate, or where else it waits); gives way with it
       def initialize(question:, mark:, options:, header: nil, details: [], hint: nil, question_code: 94,
-                     paint: ->(text, _code) { text })
+                     paint: ->(text, _code) { text }, note: nil)
         @header = header
+        @note = note
         @question = question.to_s
         @mark = mark
         @details = details
@@ -75,6 +78,7 @@ module Samagotchi
       def layout(width, hint:, details:, header:, folded:)
         rows = []
         rows << @paint.(@header, 1) if header && @header
+        rows << @paint.(@note, 2) if header && @note
         question_rows = wrap(@question, width, first: @mark, indent: " " * @mark.size)
         question_rows = question_rows.first(1) unless details
         rows.concat(question_rows.map { |row| @paint.(row, @question_code) })

data/lib/samagotchi/tool_declarations.rb

@@ -326,7 +326,7 @@ module Samagotchi
       },
       {
         name: "delegate",
-        description: "Hand a task to a child chi session that runs in parallel in this folder and returns only its final reply (its trace stays out of this context). The child is a normal session: it shows in the lists as a child of this one and the user can attach to it. With session, send a follow-up to one of this session's children instead. Children keep running if this turn is canceled; delegate_result waits for them later. A child stays until stopped: once its work is done, stop it with execute `chi sessions stop ID` (a follow-up with session wakes it again).",
+        description: "Hand a task to a child chi session that runs in parallel in this folder and returns only its final reply (its trace stays out of this context). The child is a normal session: it shows in the lists as a child of this one and the user can attach to it. With session, send a follow-up to one of this session's children instead. A tool call the child needs approved goes to your user as one of your own approvals; you only see how it was answered, as a line in the result. Children keep running if this turn is canceled; delegate_result waits for them later. A child stays until stopped: once its work is done, stop it with execute `chi sessions stop ID` (a follow-up with session wakes it again).",
         parameters: {
           type: "object",
           properties: {
@@ -356,7 +356,7 @@ module Samagotchi
       },
       {
         name: "delegate_result",
-        description: "Wait for a delegated child session's next reply: the child named, or this session's newest running child. Returns early if the child waits for an approval or a question the user must answer.",
+        description: "Wait for a delegated child session's next reply: the child named, or this session's newest running child. Returns early if the child waits for a question the user must answer. A tool call the child needs approved goes to your user while this waits; the result says how it was answered.",
         parameters: {
           type: "object",
           properties: {