samagotchi 0.12.0 → 0.14.0

data/lib/samagotchi/parent_report.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "json"
+
+require_relative "cli/exit"
+
+module Samagotchi
+  # How a wait's end (ReplyWait::Result) reads to whoever runs chi as a
+  # sub-agent: `chi send --wait` and `chi answer`. One JSON object for
+  # --format json, or a line (a block for a question) for stderr, and the
+  # exit status. A question carries everything needed to answer it, so a
+  # parent agent can answer from the output alone. Kept apart from the
+  # commands so a later delegate_answer tool reports the same shape.
+  module ParentReport
+    # The approval facts a parent needs; the rest (preview, branch) is the
+    # card's.
+    APPROVAL_KEYS = %i[tool label command paths args cwd rule source reason scopes].freeze
+
+    # stderr that keeps its last line: with --format json a failure before
+    # any wait is reported from it (#error_line).
+    class LastLine < SimpleDelegator
+      attr_reader :last
+
+      def puts(*lines)
+        @last = lines.last.to_s.chomp unless lines.empty?
+        __getobj__.puts(*lines)
+      end
+    end
+
+    module_function
+
+    # @param result [ReplyWait::Result]
+    # @return [String] answered, question, failed, canceled, no_answer,
+    #   error, worker_gone, stopped or running
+    def status(result)
+      case result.status
+      when :done then "answered"
+      when :waiting_for_answer then "question"
+      when :no_reply
+        case result.outcome
+        when "failed" then "failed"
+        when "canceled" then "canceled"
+        else "no_answer"
+        end
+      when :error then "error"
+      when :worker_gone then "worker_gone"
+      when :stopped then "stopped"
+      # ReplyWait's own :canceled is the caller giving up (its cancelled:),
+      # and :timeout the deadline: the turn goes on either way.
+      else "running"
+      end
+    end
+
+    # @return [Integer] 0 answered, 3 a question waits, 4 still running,
+    #   1 anything else
+    def exit_status(result)
+      case status(result)
+      when "answered" then CLI::Exit::OK
+      when "question" then CLI::Exit::QUESTION
+      when "running" then CLI::Exit::RUNNING
+      else CLI::Exit::FAILED
+      end
+    end
+
+    # @param session_id [String]
+    # @param timeout [Numeric, nil] the wait's --timeout (for the running detail)
+    # @return [Hash] the --format json object
+    def json(result, session_id:, timeout: nil)
+      report = { status: status(result), session_id: session_id }
+      case report[:status]
+      when "answered" then report[:text] = result.text.to_s
+      when "question"
+        question = question(result.question)
+        report[:question] = question
+        report[:answer_with] = answer_with(session_id, question)
+      else report[:detail] = detail(result, session_id: session_id, timeout: timeout)
+      end
+      report
+    end
+
+    # @return [String] the JSON object as one line
+    def json_line(result, session_id:, timeout: nil)
+      JSON.generate(json(result, session_id: session_id, timeout: timeout))
+    end
+
+    # Print a wait's end the way the commands do: the JSON object on
+    # stdout, or the reply on stdout and anything else on stderr (a
+    # question in full) after "chi send: ".
+    # @param command [String] "chi send", "chi answer"
+    # @return [Integer] the exit status
+    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil)
+      if json
+        stdout.puts(json_line(result, session_id: session_id, timeout: timeout))
+      elsif result.status == :done
+        stdout.puts(result.text)
+      else
+        stdout.flush
+        text = if result.status == :waiting_for_answer
+                 question_text(result.question, session_id: session_id)
+               else
+                 "#{detail(result, session_id: session_id, timeout: timeout)}\n"
+               end
+        stderr.print("#{command}: #{text}")
+      end
+      stdout.flush
+      exit_status(result)
+    end
+
+    # A failure before any wait (no such session, a busy one, a message
+    # that didn't go in) as the JSON object.
+    # @param session_id [String, nil]
+    def error_line(detail, session_id: nil)
+      JSON.generate({ status: "error", session_id: session_id, detail: detail.to_s })
+    end
+
+    # A pending question (Session#pending_question) as a parent sees it.
+    # kind is "question" for the model's own (the desk stores none),
+    # "hook" or "approval".
+    # @return [Hash]
+    def question(pending)
+      pending ||= {}
+      approval = pending[:approval].is_a?(Hash) ? symbolize(pending[:approval]) : nil
+      {
+        id: pending[:id].to_s,
+        kind: (pending[:kind] || "question").to_s,
+        header: blank(pending[:header]),
+        text: pending[:question].to_s,
+        options: Array(pending[:options]).map(&:to_s),
+        multi_select: !!pending[:multi_select],
+        allow_freeform: !!pending[:allow_freeform],
+        approval: approval&.slice(*APPROVAL_KEYS)
+      }.compact
+    end
+
+    # The command that answers +question+; N is the parent's to fill in.
+    # An approval's is a deny: allowing it is the user's
+    # (Guardrails::ParentApprovals).
+    def answer_with(session_id, question)
+      return "chi answer #{session_id} --question #{question[:id]} --option Deny --text WHY" if approval?(question)
+
+      "chi answer #{session_id} --question #{question[:id]} --option N"
+    end
+
+    # What a parent does with an approval.
+    DENY_AND_TELL = "deny it, and tell your user"
+
+    def approval?(question)
+      question.is_a?(Hash) && (question[:kind] || question["kind"]).to_s == "approval"
+    end
+
+    # What a wait that ended without an answer says, one line.
+    def detail(result, session_id:, timeout: nil)
+      attach = "chi --attach #{session_id}"
+      case result.status
+      when :waiting_for_answer
+        if approval?(result.question)
+          "waiting for an approval: #{first_line(result.question[:question])}; #{DENY_AND_TELL}"
+        else
+          "waiting for an answer: #{first_line(result.question&.dig(:question))}; open it: #{attach} or the web"
+        end
+      when :no_reply then "#{no_reply_line(result)}; #{attach} shows it"
+      when :error then "the worker failed: #{result.text}; #{attach} shows what happened"
+      when :worker_gone then "the worker is gone; #{attach} shows what happened"
+      when :stopped then "the session was stopped (chi sessions stop)"
+      else timeout ? "still running after #{format("%g", timeout)} s: #{attach}" : "still running: #{attach}"
+      end
+    end
+
+    # The whole question for stderr: header, text, numbered options, what
+    # else it takes, and the commands that answer it.
+    # @return [String] lines, newline-terminated
+    def question_text(pending, session_id:)
+      q = question(pending)
+      lines = ["waiting for an answer (#{q[:kind]}): #{q[:header] || first_line(q[:text])}"]
+      text_lines = q[:text].strip.lines.map(&:rstrip)
+      text_lines = text_lines.drop(1) unless q[:header]
+      lines.concat(text_lines.map { |line| "  #{line}" })
+      q[:options].each_with_index { |option, i| lines << "    #{i + 1}. #{option}" }
+      if approval?(q)
+        lines << "  allowing it is up to your user: #{DENY_AND_TELL}"
+        lines << "  deny: #{answer_with(session_id, q)}"
+      else
+        lines << "  more than one allowed: repeat --option" if q[:multi_select]
+        lines << "  free text allowed: --text" if q[:allow_freeform]
+        lines << "  answer: #{answer_with(session_id, q)}"
+        lines << "  or open it: chi --attach #{session_id} or the web"
+      end
+      lines.map { |line| "#{line}\n" }.join
+    end
+
+    def no_reply_line(result)
+      case result.outcome
+      when "failed" then result.text.to_s.strip.empty? ? "the turn failed" : "the turn failed: #{result.text.strip}"
+      when "canceled" then "the turn was canceled"
+      when "completed" then "the turn ended with no visible answer"
+      else "the turn ended without a reply (canceled, failed or empty)"
+      end
+    end
+
+    def first_line(text)
+      text.to_s.strip.lines.first.to_s.strip
+    end
+
+    def blank(value)
+      value.to_s.strip.empty? ? nil : value.to_s
+    end
+
+    def symbolize(hash)
+      hash.each_with_object({}) { |(key, value), out| out[key.to_sym] = value }
+    end
+  end
+end

data/lib/samagotchi/plugin/api.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "../log"
 require_relative "../hooks/registry"
 require_relative "../tools/args"
@@ -298,14 +299,26 @@ module Samagotchi
           schema: spec[:schema], label: spec[:label],
           handler: lambda { |call, _kctx|
             result = block.call(Api.args_of(call, parameters), context)
-            # A String (a ToolResult too, with its images) as it is.
-            result.is_a?(String) ? result : result.to_s
+            Api.result_text(result)
           },
           preview: preview && ->(call) { preview.call(Api.args_of(call, parameters))&.to_s },
           targets: targets && ->(call) { targets.call(Api.args_of(call, parameters)) }
         }
       end
 
+      # A tool's result as the model reads it: a String (a ToolResult too,
+      # with its images) as it is, a Hash or Array as JSON (its #to_s is
+      # Hash#inspect, which changes with the Ruby version), else #to_s.
+      def self.result_text(result)
+        case result
+        when String then result
+        when Hash, Array then JSON.generate(result)
+        else result.to_s
+        end
+      rescue JSON::GeneratorError
+        result.to_s
+      end
+
       # A tool call's arguments as a plugin sees them: the parsers' args:
       # (a call built without one, in a spec say: the call without its
       # name), string keys, typed by +parameters+, frozen.

data/lib/samagotchi/prompt_literal_guard.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "model_profile"
+
 module Samagotchi
   # Escapes literal control-token text when arbitrary source/output is embedded
   # inside prompts, then restores those placeholders when model text is used.
@@ -13,8 +15,8 @@ module Samagotchi
       ["[[SAMAGOTCHI_LITERAL_TOOL_RESPONSE_CLOSE]]", "<tool_response|>"],
       ["[[SAMAGOTCHI_LITERAL_GEMMA_STRING_DELIM]]", '<|"|>'],
       ["[[SAMAGOTCHI_LITERAL_THINK_OPEN]]", "<|think|>"],
-      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_OPEN]]", "<|channel>thought"],
-      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_CLOSE]]", "<channel|>"]
+      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_OPEN]]", ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN],
+      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_CLOSE]]", ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE]
     ].freeze
 
     QWEN_TOKEN_PAIRS = [

data/lib/samagotchi/question_desk.rb

@@ -7,6 +7,7 @@ require "time"
 
 require_relative "log"
 require_relative "tools/ask_user_question"
+require_relative "guardrails/parent_approvals"
 
 module Samagotchi
   # An Engine's question flow: the one open question (ask_user_question, a
@@ -21,6 +22,20 @@ module Samagotchi
     # of ArgumentError for existing callers; transports map it to 409 Conflict.
     class NotPending < ArgumentError; end
 
+    # Raised by #answer when a parent agent's answer (chi answer's client
+    # id) allows an approval further than this worker's
+    # guardrails.parent_approvals lets it (Guardrails::ParentApprovals).
+    # The question stays open; transports map it to 403.
+    class Refused < StandardError
+      # @return [Symbol] :off or :once_only
+      attr_reader :reason
+
+      def initialize(reason)
+        @reason = reason
+        super("a parent may not allow this approval (#{reason})")
+      end
+    end
+
     DISMISSED_NOTE = "The user dismissed the question without answering. Don't do what you asked about, " \
                      "or anything else that changes files or state. Finish your reply with what you found " \
                      "and what you would do, and wait."
@@ -170,11 +185,16 @@ module Samagotchi
     # @param id [String] pending id
     # @param selected [Array<String>] values/labels
     # @param freeform [String, nil]
+    # @param client_id [String, nil] who answers; chi answer's (a parent
+    #   agent) is held to guardrails.parent_approvals on an approval
     # @return [Hash] normalized answer
-    def answer(id:, selected:, freeform: nil)
+    # @raise [NotPending, ArgumentError, Refused]
+    def answer(id:, selected:, freeform: nil, client_id: nil)
       sel = Array(selected).map { |v| v.to_s.strip }.reject(&:empty?)
       fm = freeform.to_s.strip
       fm = nil if fm.empty?
+      # Read before the lock (config may touch the disk); this worker's own.
+      parent_setting = Guardrails::ParentApprovals.setting if client_id.to_s == Guardrails::ParentApprovals::CLIENT_ID
       @lock.synchronize do
         pending = @pending
         raise NotPending, "no pending question" unless pending
@@ -197,10 +217,17 @@ module Samagotchi
         if pending[:multi_select] == false && sel.empty? && fm.nil?
           raise ArgumentError, "selection required"
         end
+        indices = sel.map { |v| opts.index(v) }
+        # Checked against the question pending now, under the lock: the one
+        # whose answer settles the approval (Approval.settle, by index).
+        if parent_setting
+          reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: parent_setting)
+          raise Refused, reason if reason
+        end
         # Persist pending cleared elsewhere; just set answer
         answer = { id: id.to_s, selected: sel, freeform: fm }
         # Derive indices for convenience
-        answer[:selected_indices] = sel.map { |v| opts.index(v) }.compact
+        answer[:selected_indices] = indices.compact
         @answer = answer
         @cv.broadcast
         answer

data/lib/samagotchi/recap_setup.rb

@@ -13,7 +13,8 @@ module Samagotchi
     # host or model configured it asks the session's current model on its
     # host, resolved at each attempt the way a turn does (a /model switch
     # counts). An explicit `recap: {host_ref:, model:}` or `{base_url:,
-    # model:}` pins it; an incomplete one warns and leaves recap off.
+    # model:}` pins it; a model alone goes to its host, or where a bare
+    # --model goes; an incomplete one warns and leaves recap off.
     #
     # Single precedence path: explicit `recap:` kwarg > Config registry
     # (CLI > ENV > file > default). An explicit disable (`recap: false` as
@@ -42,14 +43,23 @@ module Samagotchi
       model = string_config(kwarg_config, :model) || registry_string("recap.model")
       label = model
 
+      # The model as any model ref (ModelRef): its alias applied once, and
+      # its host (own or the alias's) picks the recap host when host_ref
+      # doesn't.
+      parsed = model && host_registry.model_ref(model)
       target = nil
       if base_url.nil? && host_ref.nil? && model.nil?
         target = -> { session_target.call }
+      elsif base_url.nil? && host_ref.nil? && !parsed.host_name
+        # A model naming no host goes where a bare --model goes
+        # (HostRegistry#host_for_model: the default host unless another's
+        # list has it), resolved at each attempt.
+        target = lambda do
+          resolved = host_registry.resolve(model)
+          { base_url: resolved.openai_base_url, api_key_env: resolved.entry.api_key_env,
+            model: resolved.bare_model, label: label.to_s.strip }
+        end
       else
-        # The model as any model ref (ModelRef): its alias applied once, and
-        # its host (own or the alias's) picks the recap host when host_ref
-        # doesn't.
-        parsed = model && host_registry.model_ref(model)
         host_ref ||= parsed.host_name if parsed && base_url.nil?
         # If host_ref given, derive base_url (the host's OpenAI base) and its
         # API key variable from the host_registry entry

data/lib/samagotchi/reply_wait.rb

@@ -72,8 +72,12 @@ module Samagotchi
           return Result.new(status: :stopped)
         end
 
+        # Only a question a live worker holds waits for an answer (the
+        # lists' rule): one a dead worker left waits for no one, and a chi
+        # REPL's is answered there.
         pending = session.pending_question
-        if pending && !(baseline && pending[:id] == baseline[:question_id])
+        if pending && !(baseline && pending[:id] == baseline[:question_id]) &&
+           session.waiting_question(live: SessionManager.worker_live?(id, state_dir: state_dir))
           return Result.new(status: :waiting_for_answer, question: pending)
         end
 

data/lib/samagotchi/send_command.rb

@@ -5,12 +5,14 @@ require_relative "session_inbox"
 require_relative "session_manager"
 require_relative "context_quote"
 require_relative "reply_wait"
+require_relative "parent_report"
 require_relative "image_store"
 require_relative "host_registry"
 require_relative "model_profile"
 require_relative "vision_support"
 require_relative "cli/command"
 require_relative "cli/flags"
+require_relative "cli/parent_wait"
 
 module Samagotchi
   # `chi send`: put text into sessions as the user's message, the same as
@@ -22,20 +24,17 @@ module Samagotchi
   # prints it: an agent's one-shot the user can watch in the web.
   class SendCommand
     include CLI::Command
+    include CLI::ParentWait
 
     CLIENT_ID = "cli:send"
-    POLL_INTERVAL = ReplyWait::POLL_INTERVAL
-    # No live worker this long while waiting: it died before it could mark
-    # the session (a worker takes well under a second to start).
-    WORKER_GONE_AFTER = 5
     # The cap on one turn's images the Bridge checks.
     MAX_IMAGES = ImageStore::MAX_TURN_REFS
 
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...
              chi send --new [--dir DIR] [--model M] [-m TEXT] [--image PATH]...
-             chi send --wait [--timeout S] [-m TEXT] [--image PATH]... (--new | ID)
-             chi send --wait [--timeout S] ID
+             chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
+             chi send --wait [--timeout S] [--format json] ID
         Sends a message to each session, as if typed in it: a turn starts,
         or a running one picks it up. A stopped session's worker starts.
         -m TEXT     the message; stdin, when piped too, goes above it as a
@@ -53,11 +52,21 @@ module Samagotchi
         --model M   (--new) its model; default the configured one
         --wait      wait for the answer and print it (one session); the
                     other lines go to stderr. Exit 3: it waits for an
-                    answer from you (chi --attach ID or the web). With
-                    no message (no -m, nothing piped) nothing is sent: it
-                    waits for the session's next reply, a running turn's
-                    too (after exit 3 or 130, wait again this way)
-        --timeout S (--wait) give up after S seconds; default no limit
+                    answer from you: the question, its options and the
+                    chi answer command go to stderr (or chi --attach ID,
+                    the web). With no message (no -m, nothing piped)
+                    nothing is sent: it waits for the session's next
+                    reply, a running turn's too (after exit 3, 4 or 130,
+                    wait again this way)
+        --timeout S (--wait) give up after S seconds, exit 4 (the turn
+                    goes on); default no limit
+        --format json
+                    (--wait) one JSON object on stdout, whatever the end:
+                    status answered (text), question (question,
+                    answer_with), running, or failed, canceled,
+                    no_answer, error, worker_gone, stopped (detail)
+        Exit with --wait: 0 answered, 1 failed or gone, 2 usage, 3 a
+        question waits, 4 still running (--timeout), 130 Ctrl-C.
         Only sessions on this machine. Answers show in the attached TUI
         or web page, not here.
         Find ids with: chi sessions list --live [--scope=all] [--format tsv]
@@ -71,6 +80,7 @@ module Samagotchi
       f.value "--image", key: :images, repeat: true
       f.switch "--wait"
       f.value "--timeout"
+      f.value "--format"
       # Starting a turn in every live session at once is too easy to do
       # by accident.
       f.refuse "--all", "there is no --all: name the sessions"
@@ -119,13 +129,13 @@ module Samagotchi
       @state_dir = state_dir || Session.default_state_dir
     end
 
-    # @return [Integer] exit status: 0 all sent, 1 any refused or failed,
-    #   2 usage; with --wait 0 answered, 3 waiting for an answer, 130
-    #   Ctrl-C (the turn goes on)
-    def run
-      options = parse
-      return options if options.is_a?(Integer)
+    private
 
+    # Under #run (CLI::ParentWait).
+    # @return [Integer] exit status: 0 all sent, 1 any refused or failed,
+    #   2 usage; with --wait 0 answered, 3 waiting for an answer, 4 still
+    #   running after --timeout, 130 Ctrl-C (the turn goes on)
+    def run_parsed(options)
       # With --wait stdout is the answer alone.
       @info = options[:wait] ? @stderr : @stdout
       prompt = compose(utf8(read_stdin), utf8(options[:message]))
@@ -140,7 +150,9 @@ module Samagotchi
         @stderr.puts("chi send: #{e.message}")
         return 1
       end
-      return 2 unless ingest_images(options[:images])
+      # A file that is not there or not an image: a run-time failure (1),
+      # reported in the --format json line too; --image itself was fine.
+      return CLI::Exit::FAILED unless ingest_images(options[:images])
 
       return run_new(prompt, options) if options[:new]
       return run_wait(prompt, options) if options[:wait]
@@ -160,8 +172,6 @@ module Samagotchi
       FileUtils.rm_rf(@image_dir) if @image_dir
     end
 
-    private
-
     def command_name = "chi send"
 
     # @return [Hash, Integer] the options, or the exit status after the
@@ -171,6 +181,10 @@ module Samagotchi
       return parsed if parsed.is_a?(Integer)
 
       options = parsed.options.merge(ids: parsed.args)
+      if options[:format]
+        return usage_error("--format needs --wait") unless options[:wait]
+        return usage_error("--format takes text or json") unless FORMATS.include?(options[:format])
+      end
       if options[:timeout]
         return usage_error("--timeout needs --wait") unless options[:wait]
 
@@ -220,16 +234,6 @@ module Samagotchi
       @stdin.read
     end
 
-    def resolve(given)
-      id = Session.resolve_id(given, state_dir: @state_dir)
-      Session.load(id, state_dir: @state_dir)
-      id
-    rescue ArgumentError => e
-      message = e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"
-      error_line("chi send: #{message}")
-      nil
-    end
-
     # A worker session like the web start page's: saved as running with the
     # message before its worker spawns, so lists and the web show it at
     # once. The full id, so a script can pass it on. Only the model's host
@@ -257,6 +261,7 @@ module Samagotchi
       else
         @info.puts("#{session.id}  started")
       end
+      @session_id = session.id
       return 0 unless options[:wait]
 
       wait_for_reply(session.id, cursor: nil, baseline: baseline_of(session, question_id: nil),
@@ -272,8 +277,20 @@ module Samagotchi
     def run_wait(prompt, options)
       id = resolve(options[:ids].first) or return 1
       session = Session.load(id, state_dir: @state_dir)
-      if session.status == Session::STATUS_RUNNING && SessionManager.session_owner(id, state_dir: @state_dir)
-        error_line("#{id[0, 8]}  busy: a turn is running; wait or attach")
+      if session.status == Session::STATUS_RUNNING && (owner = SessionManager.session_owner(id, state_dir: @state_dir))
+        # The turn waits on a question: the message would only queue
+        # behind it, and the answer goes in with chi answer.
+        if (waiting = session.waiting_question(live: owner.worker?))
+          if ParentReport.approval?(waiting)
+            error_line("#{id[0, 8]}  waiting for an approval: #{ParentReport::DENY_AND_TELL} " \
+                       "(#{ParentReport.answer_with(id, waiting)})")
+          else
+            error_line("#{id[0, 8]}  waiting for an answer: #{ParentReport.answer_with(id, waiting)} (or --text); " \
+                       "chi --attach #{id} shows it")
+          end
+        else
+          error_line("#{id[0, 8]}  busy: a turn is running; wait or attach")
+        end
         return 1
       end
 
@@ -298,7 +315,7 @@ module Samagotchi
       live = session.status == Session::STATUS_RUNNING || SessionManager.session_owner(id, state_dir: @state_dir)
       wait_for_reply(id, cursor: ReplyWait.newest_reply(id, state_dir: @state_dir),
                          baseline: baseline_of(session).merge(messages: nil),
-                         timeout: options[:timeout], owner_grace: live ? WORKER_GONE_AFTER : nil)
+                         timeout: options[:timeout], owner_grace: live ? self.class::WORKER_GONE_AFTER : nil)
     end
 
     # The session as it was before the message went in (ReplyWait's
@@ -307,48 +324,6 @@ module Samagotchi
       ReplyWait.baseline_of(session, **options)
     end
 
-    # @return [Integer] the exit status
-    def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: WORKER_GONE_AFTER)
-      result = ReplyWait.call(id, state_dir: @state_dir, cursor: cursor, timeout: timeout, baseline: baseline,
-                                  owner_grace: owner_grace, poll_interval: POLL_INTERVAL)
-      return reply(result.text) if result.status == :done
-
-      attach = "chi --attach #{id}"
-      line, status = case result.status
-                     when :waiting_for_answer
-                       question = result.question[:question].to_s.strip.lines.first.to_s.strip
-                       ["waiting for an answer: #{question}; open it: #{attach} or the web", 3]
-                     when :no_reply then ["#{no_reply_line(result)}; #{attach} shows it", 1]
-                     when :error then ["the worker failed: #{result.text}; #{attach} shows what happened", 1]
-                     when :worker_gone then ["the worker is gone; #{attach} shows what happened", 1]
-                     when :stopped then ["the session was stopped (chi sessions stop)", 1]
-                     else ["still running after #{format("%g", timeout)} s: #{attach}", 1]
-                     end
-      error_line("chi send: #{line}")
-      status
-    rescue Interrupt
-      error_line("chi send: still running: chi --attach #{id}")
-      130
-    rescue ArgumentError
-      error_line("chi send: the session is gone (deleted while waiting)")
-      1
-    end
-
-    def no_reply_line(result)
-      case result.outcome
-      when "failed" then result.text.to_s.strip.empty? ? "the turn failed" : "the turn failed: #{result.text.strip}"
-      when "canceled" then "the turn was canceled"
-      when "completed" then "the turn ended with no visible answer"
-      else "the turn ended without a reply (canceled, failed or empty)"
-      end
-    end
-
-    def reply(text)
-      @stdout.puts(utf8(text))
-      @stdout.flush
-      0
-    end
-
     # A new idle session's first turn, with the images. Its worker's Bridge
     # first: deliver_turn wakes a worker when none owns the session yet,
     # and the spawned one takes its lock only once it runs.

data/lib/samagotchi/session.rb

@@ -99,6 +99,21 @@ module Samagotchi
       @archived = false
     end
 
+    # The question this session waits on, as the lists show it: {id:, kind:}
+    # with kind "question" (the model's), "approval" or "hook"; nil with
+    # none. Only while a worker runs it (+live+): a question saved by a
+    # worker that died waits for no one (the next worker drops it). The
+    # web's summaries and `chi sessions list` both ask this.
+    # @param live [Boolean] a worker owns the session now
+    # @return [Hash, nil]
+    def waiting_question(live:)
+      pending = pending_question
+      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" }
+    end
+
     # The stored project root, else (a file from before the field) the
     # project of the working directory now: nil when that is in no repo or
     # gone. +cache+ is ProjectScope.root_for's, shared across one listing.