samagotchi 0.76.0 → 0.77.0

data/lib/samagotchi/message_parts.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require_relative "model_profile"
+require_relative "tool_call_parser"
+require_relative "tool_activity"
+require_relative "tool_row_fields"
+require_relative "llm/native_tool_normalizer"
+require_relative "tools/builtins"
+require_relative "image_store"
+require_relative "llm_context_edit"
+require_relative "token_usage"
+require_relative "row_refs"
+require_relative "tool_output_cut"
+
+module Samagotchi
+  # What a saved assistant message did, for a turn view's reload: its
+  # thinking and its tool calls (name, the params line the live row shows,
+  # the output from the tool_response messages after it). Two storage
+  # shapes, best effort:
+  #   * the native loop (a profile, llama.cpp): the raw response as content
+  #     (thinking + tool-call markup, Qwen or Gemma), then one tool_response
+  #     whose content joins every call's output with "\n\n---\n\n";
+  #   * the chat loop (api: openai): the text without thinking, the host's
+  #     reasoning as +thinking+ (older sessions have none), the calls as
+  #     tool_calls ({id, name, arguments}), then one tool_response per call
+  #     (tool_call_id).
+  # A message that can't be read gives no parts, never an error.
+  #
+  # A call's images (a read image, a plugin or MCP tool's) are on its
+  # tool_response: chat, per call; native, one list for every call, split
+  # by the saved image_counts (older sessions without them: only a lone
+  # call gets them).
+  #
+  # A call's chi-owned id (ToolIds, saved as tool_ids) is the part's
+  # tool_id:, and an LLM context edit saved on its output (LLMContextEdit,
+  # under edits) the part's edit: (.edit_marks), the row's ✂ mark.
+  #
+  # A plugin tool's params are what its live row showed (its preview),
+  # saved with the result as tool_params (native: one per call, chat: one
+  # per result); its label ("chrome: screenshot") likewise as tool_labels,
+  # the part's label:, and its row refs as tool_refs (RowRefs, checked
+  # again here), the part's refs:. The web server has no Engine and runs no plugins, so a
+  # result without them (older sessions) falls back to the given
+  # registry: the built-ins', and a plugin tool's arguments as key="value"
+  # from the parsers' args:, as the live row shows them for a tool
+  # without a preview.
+  module MessageParts
+    JOINER = "\n\n---\n\n"
+    # A joined output's pieces each start with "[tool]": split there first,
+    # so an output that holds the joiner itself stays whole.
+    JOINER_BEFORE_TAG = /\n\n---\n\n(?=\[)/
+    # The row shows 300 chars and the rest on hover; a read of a big file
+    # would otherwise ride along with every reload. A longer one keeps its
+    # head and tail (ToolOutputCut.preview).
+    OUTPUT_MAX = ToolOutputCut::WEB_PREVIEW_CHARS
+
+    QWEN_THINK = %r{<think>(.*?)</think>}m
+    QWEN_OPEN_THINK = %r{\A(.*?)</think>}m # the template opened the block
+    GEMMA_THOUGHT = Regexp.new("#{Regexp.escape(ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN)}(.*?)" \
+                               "(?:#{Regexp.escape(ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE)}|\\z)", Regexp::MULTILINE)
+
+    CallRef = Struct.new(:name, :arguments)
+
+    module_function
+
+    # @param message [Hash] a saved model message (symbol or string keys)
+    # @param responses [Array<Hash>] the tool_response messages after it
+    # @param registry [Tools::Registry] the session's tools
+    # @param cwd [String, nil] the session's working directory (a file
+    #   tool's title is relative to it)
+    # @param marks [Hash{String => Hash}] the session's edit marks by
+    #   output id (.edit_marks)
+    # @return [Hash, nil] { thinking:, tools: [{ tool:, params:, title:,
+    #   output:, output_truncated:, images:, tool_id:, edit: }] } with only what it found; nil for nothing
+    def for_message(message, responses, registry: Tools::Builtins.default, cwd: nil, marks: {})
+      content = field(message, :content).to_s
+      calls = field(message, :tool_calls)
+      tools = if calls.is_a?(Array) && !calls.empty?
+                native_tools(calls, responses, registry, cwd, marks)
+              else
+                markup_tools(content, responses, registry, cwd, marks)
+              end
+      parts = {}
+      thinking = [field(message, :thinking).to_s.strip, thinking_of(content)].reject(&:empty?).join("\n\n")
+      parts[:thinking] = thinking unless thinking.empty?
+      parts[:tools] = tools unless tools.empty?
+      parts.empty? ? nil : parts
+    rescue StandardError
+      nil
+    end
+
+    def thinking_of(content)
+      blocks = content.scan(QWEN_THINK).flatten
+      if blocks.empty? && !content.include?("<think>") && (open = content[QWEN_OPEN_THINK, 1])
+        blocks = [open]
+      end
+      blocks += content.scan(GEMMA_THOUGHT).flatten
+      blocks.map(&:strip).reject(&:empty?).join("\n\n")
+    end
+
+    def markup_tools(content, responses, registry, cwd = nil, marks = {})
+      calls = []
+      calls.concat(ToolCallParser::Qwen.new(ModelProfile.qwen36).parse(content)) if content.include?("<tool_call>")
+      calls.concat(ToolCallParser::Gemma.new(ModelProfile.gemma4).parse(content)) if content.include?("<|tool_call>")
+      return [] if calls.empty?
+
+      joined = responses.empty? ? nil : responses.map { |r| field(r, :content).to_s }.join(JOINER)
+      outputs = split_outputs(joined, calls.length)
+      shown = saved_list(responses, :tool_params, calls.length)
+      labels = saved_list(responses, :tool_labels, calls.length)
+      diffs = saved_list(responses, :tool_diffs, calls.length)
+      refs = saved_list(responses, :tool_refs, calls.length)
+      ids = saved_list(responses, :tool_ids, calls.length)
+      images = split_images(responses, calls.length)
+      calls.each_with_index.map do |call, i|
+        tool_part(call, outputs[i], registry, shown[i], images[i], label: labels[i], diff: diffs[i], refs: refs[i],
+                                                                   cwd: cwd, tool_id: ids[i], marks: marks)
+      end
+    end
+
+    # A per-call list saved with the joined result(s), or none when its
+    # length doesn't match the calls.
+    def saved_list(responses, key, count)
+      list = responses.flat_map { |r| Array(field(r, key)) }
+      list.length == count ? list : []
+    end
+
+    # Each call's images from the joined tool_response(s).
+    def split_images(responses, count)
+      images = responses.flat_map { |r| Array(field(r, :images)) }
+      return [] if images.empty?
+
+      counts = responses.flat_map { |r| Array(field(r, :image_counts)) }
+      return count == 1 ? [images] : [] unless counts.length == count && counts.sum == images.length
+
+      counts.map { |n| images.shift(n) }
+    end
+
+    def native_tools(calls, responses, registry, cwd = nil, marks = {})
+      # By id only for an id that names one response: a server may omit
+      # it (nil), send "" or repeat it; those pair by position.
+      ids = responses.map { |r| field(r, :tool_call_id).to_s }
+      unique = ->(id) { !id.empty? && ids.count(id) == 1 }
+      by_id = responses.each_with_index.to_h { |r, i| [ids[i], r] }.select { |id, _| unique.call(id) }
+      calls.each_with_index.map do |raw, i|
+        ref = CallRef.new(field(raw, :name).to_s, field(raw, :arguments))
+        call = LLM::NativeToolNormalizer.normalize(ref) || { name: ref.name }
+        response = by_id[field(raw, :id).to_s] || (responses[i] && !unique.call(ids[i]) ? responses[i] : nil)
+        tool_part(call, response && field(response, :content).to_s, registry, field(response, :tool_params),
+                  response && field(response, :images), label: field(response, :tool_labels),
+                                                        diff: field(response, :tool_diffs),
+                                                        refs: field(response, :tool_refs), cwd: cwd,
+                                                        tool_id: Array(field(response, :tool_ids)).first, marks: marks)
+      end
+    end
+
+    # The ✂ mark of each output an LLM context edit is saved on, by its
+    # id, from +messages+ (a session's, symbol or string keys): {kind:
+    # "stale" | "forget", staged: true while a forget waits for the
+    # turn's end, note: (a stale stub's reason, "superseded by a later
+    # read"; the first output of a forget_outputs call's, its note), with:
+    # (the others of that call's: the first one's id), kept: ("12-40, 50",
+    # a forget's kept lines)}. A forget call's outputs share the note,
+    # author and stamp (LLMContextView's key); the first in the session's
+    # order carries the note.
+    # @return [Hash{String => Hash}]
+    def edit_marks(messages)
+      first = {}
+      Array(messages).each_with_object({}) do |entry, marks|
+        next unless field(entry, :role).to_s == "tool_response"
+
+        saved = field(entry, :edits)
+        next unless saved.is_a?(Hash)
+
+        edits = saved.filter_map { |id, hash| LLMContextEdit.from_h(id, hash) }.to_h { |edit| [edit.id, edit] }
+        order = Array(field(entry, :tool_ids)).map(&:to_s)
+        edits.sort_by { |id, _| order.index(id) || order.size }.each do |id, edit|
+          marks[id] = edit_mark(edit, first)
+        end
+      end
+    rescue StandardError
+      {}
+    end
+
+    def edit_mark(edit, first)
+      mark = { kind: edit.kind.to_s }
+      mark[:staged] = true unless edit.applied?
+      if edit.kind == :stale
+        mark[:note] = edit.note[/superseded by .*\z/] || edit.note
+      else
+        key = [edit.note, edit.by, edit.staged_at]
+        if first.key?(key)
+          mark[:with] = first[key]
+        else
+          first[key] = edit.id
+          mark[:note] = edit.note
+        end
+        kept = edit.keep.map { |from, to| from == to ? from.to_s : "#{from}-#{to}" }
+        mark[:kept] = kept.join(", ") unless kept.empty?
+      end
+      mark
+    end
+
+    # +output+'s ✂ mark (+marks+ by +id+); an applied stale stub says
+    # what it frees: its output, ~chars/4.
+    def mark_of(id, marks, output)
+      mark = marks[id]
+      return nil unless mark
+      return mark unless mark[:kind] == "stale" && !mark[:staged] && output
+
+      mark.merge(tokens: (output.length / TokenUsage::CHARS_PER_TOKEN).ceil)
+    end
+
+    # +count+ outputs from a joined tool_response: the "[tool]"-tagged
+    # split when it gives the right count, else the plain one; extra pieces
+    # stay with the last call, missing ones are nil.
+    def split_outputs(joined, count)
+      return [] if joined.nil?
+      return [joined] if count == 1
+
+      pieces = joined.split(JOINER_BEFORE_TAG, -1)
+      pieces = joined.split(JOINER, -1) if pieces.length != count
+      return pieces if pieces.length == count
+
+      head = pieces.first(count - 1)
+      rest = pieces.drop(count - 1)
+      head + [rest.empty? ? nil : rest.join(JOINER)]
+    end
+
+    # +shown+ is the saved params line, when it is a String.
+    # +diff+ is what an edit/write changed (EditPreview.change), saved as
+    # tool_diffs. +refs+: a plugin tool's row refs, saved as tool_refs
+    # (RowRefs.for_display checks them again against +cwd+). +cwd+: the
+    # session's working directory, for the title.
+    # +tool_id+: its output's ToolIds id, with its ✂ mark in +marks+.
+    def tool_part(call, output, registry, shown = nil, images = nil, label: nil, diff: nil, refs: nil, cwd: nil,
+                  tool_id: nil, marks: {})
+      # A built-in reached through call_tool reloads as that built-in's
+      # row, with via (its saved params and label are the built-in's).
+      call = Tools::BuiltinCalls.unwrap_saved(call, output)
+      name = call[:name].to_s
+      params = shown.is_a?(String) ? shown : ToolActivity.tool_activity_params(name, call, registry: registry)
+      part = { tool: name, params: params.to_s }
+      # Its row fields (ToolRowFields: title, called_as, via, view, ref), built from the saved
+      # call (never saved themselves), so older sessions get them too. The
+      # saved call is rebuilt by BuiltinCalls, which sets called_as and via again.
+      part.merge!(ToolRowFields.for(name, call, cwd: cwd))
+      part[:label] = label if label.is_a?(String) && !label.empty?
+      unless output.nil?
+        part[:output] = ToolOutputCut.preview(output, cap: OUTPUT_MAX, tool: name)
+        part[:output_truncated] = true if output.length > OUTPUT_MAX
+      end
+      shots = Array(images).select { |image| image.is_a?(Hash) }
+      part[:images] = shots.map { |image| ImageStore.symbolize(image).slice(:file, :name, :width, :height) } unless shots.empty?
+      part[:diff] = diff if diff.is_a?(Hash)
+      row_refs = RowRefs.for_display(refs, cwd: cwd)
+      part[:refs] = row_refs unless row_refs.empty?
+      if tool_id
+        part[:tool_id] = tool_id.to_s
+        mark = mark_of(tool_id.to_s, marks, output)
+        part[:edit] = mark if mark
+      end
+      part
+    end
+
+    def field(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      hash.key?(key) ? hash[key] : hash[key.to_s]
+    end
+  end
+end

data/lib/samagotchi/parent_report.rb

@@ -4,6 +4,7 @@ require "delegate"
 require "json"
 
 require_relative "cli/exit"
+require_relative "pending_question"
 
 module Samagotchi
   # How a wait's end (ReplyWait::Result) reads to whoever runs chi as a
@@ -136,23 +137,24 @@ module Samagotchi
       JSON.generate({ status: "error", session_id: session_id, detail: detail.to_s })
     end
 
-    # A pending question (Session#pending_question) as a parent sees it.
+    # A pending question (Session#pending_question, a PendingQuestion) as a
+    # parent sees it.
     # kind is "question" for the model's own (the desk stores none),
     # "hook", "approval" or "continue" (the step-limit question, with the
     # turn's limit).
     # @return [Hash]
     def question(pending)
-      pending ||= {}
-      approval = pending[:approval].is_a?(Hash) ? symbolize(pending[:approval]) : nil
+      pending ||= PendingQuestion.new
+      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],
-        limit: pending[:limit],
+        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,
+        limit: pending.limit,
         approval: approval&.slice(*APPROVAL_KEYS)
       }.compact
     end
@@ -178,13 +180,18 @@ module Samagotchi
         "chi send --wait --format json #{session_id} waits until they answer"
     end
 
-    def approval?(question)
-      question.is_a?(Hash) && (question[:kind] || question["kind"]).to_s == "approval"
-    end
+    # @param question [PendingQuestion, Hash, nil] a pending question, or a
+    #   Hash with its kind (#question's, Session#waiting_question's)
+    def approval?(question) = kind_of(question) == "approval"
 
     # The step-limit question (ContinueOffer).
-    def continue?(question)
-      question.is_a?(Hash) && (question[:kind] || question["kind"]).to_s == "continue"
+    def continue?(question) = kind_of(question) == "continue"
+
+    def kind_of(question)
+      case question
+      when PendingQuestion then question.kind.to_s
+      when Hash then (question[:kind] || question["kind"]).to_s
+      end
     end
 
     # What a message does to a step-limit question.
@@ -197,13 +204,14 @@ module Samagotchi
       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}"
-        elsif continue?(result.question)
-          "waiting at the step limit: #{first_line(result.question[:question])}; " \
-            "answer Continue or Stop: chi answer #{session_id} --question #{result.question[:id]} --option Continue"
+        q = question(result.question)
+        if approval?(q)
+          "waiting for an approval: #{first_line(q[:text])}; #{DENY_AND_TELL}"
+        elsif continue?(q)
+          "waiting at the step limit: #{first_line(q[:text])}; " \
+            "answer Continue or Stop: chi answer #{session_id} --question #{q[:id]} --option Continue"
         else
-          "waiting for an answer: #{first_line(result.question&.dig(:question))}; open it: #{attach} or the web"
+          "waiting for an answer: #{first_line(q[:text])}; open it: #{attach} or the web"
         end
       when :no_reply then "#{no_reply_line(result, session_id)}; #{attach} shows it"
       when :error then "the worker failed: #{result.text}; #{attach} shows what happened"

data/lib/samagotchi/pending_question.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The one open question of a session (QuestionDesk's pending question,
+  # Session#pending_question): the model's ask_user_question, a hook's
+  # ask_user, a guardrail approval, a relayed delegate approval or the
+  # step-limit question (kind "continue").
+  #
+  # id: the question's uuid; question, options, header, multi_select,
+  # allow_freeform: what the UIs show; kind: nil for the model's own,
+  # "hook", "approval" or "continue"; hook: the asking hook's name;
+  # approval: the approval's facts (Guardrails::Approval.payload); relay: a
+  # relayed approval's facts (Relay.card); limit, context: the step-limit
+  # question's turn limit and offer context (ContinueOffer); status:
+  # "pending" or "cancelled"; created_at: iso8601; relayed_to: the relay
+  # mark ({parent_id:, parent_short:, relay_id:}, QuestionDesk#annotate).
+  # approval, relay, context and relayed_to stay Hashes as given (string
+  # keys inside after a load). A field may be nil (unset).
+  #
+  # Crosses the process as a Hash: #to_h for an event, a Bridge snapshot or
+  # a UI (symbol keys), #to_file for session.json (string keys); both in
+  # member order with unset fields left out. .from_file reads either back.
+  PendingQuestion = Data.define(:id, :question, :options, :header, :multi_select, :allow_freeform, :kind, :hook,
+                                :approval, :relay, :limit, :context, :status, :created_at, :relayed_to) do
+    def initialize(**fields)
+      super(**members.to_h { |m| [m, nil] }, **fields)
+    end
+
+    # A saved or sent record (string or symbol keys, a key we don't know
+    # dropped), a PendingQuestion as it is; nil for anything else.
+    # @return [PendingQuestion, nil]
+    def self.from_file(raw)
+      return raw if raw.is_a?(PendingQuestion)
+      return nil unless raw.is_a?(Hash)
+
+      new(**members.to_h { |m| [m, raw.key?(m.to_s) ? raw[m.to_s] : raw[m]] })
+    end
+
+    # The event / snapshot shape: symbol keys, in member order, unset
+    # fields left out.
+    # @return [Hash{Symbol => Object}]
+    def to_h = super.compact
+
+    # The session file's record: string keys, in member order, unset
+    # fields left out.
+    # @return [Hash{String => Object}]
+    def to_file = to_h.transform_keys(&:to_s)
+  end
+end

data/lib/samagotchi/question_desk.rb

@@ -7,6 +7,7 @@ require "time"
 
 require_relative "client_id"
 require_relative "log"
+require_relative "pending_question"
 require_relative "tools/ask_user_question"
 require_relative "guardrails/parent_approvals"
 require_relative "guardrails/parent_continue"
@@ -87,6 +88,8 @@ module Samagotchi
       # A Monitor: re-entered by the specs from the same thread.
       @lock = Monitor.new
       @cv = @lock.new_cond
+      # The open question (PendingQuestion), nil with none; replaced, never
+      # changed in place (#annotate, #cancel make a new one with #with).
       @pending = nil
       @answer = nil
       # Why the open question was cancelled (#cancel), for the sync path.
@@ -99,9 +102,10 @@ module Samagotchi
       @shelved = nil
     end
 
-    # @return [Hash, nil] current pending question (thread-safe copy)
+    # @return [PendingQuestion, nil] the question pending now (a value: it
+    #   never changes once read)
     def pending
-      @lock.synchronize { @pending&.dup }
+      @lock.synchronize { @pending }
     end
 
     # Ask the model's question (ask_user_question): the kernel's
@@ -127,8 +131,9 @@ module Samagotchi
     # Open a question for the UIs and wait for its answer. Emits
     # :question_requested, persists it to the session, and BLOCKS until
     # answer / cancel wakes it (or the turn is cancelled).
-    # The fields go to pending as given (no cleaning), extra keys
-    # included, so a caller can add its own (kind:, approval:).
+    # The fields become the PendingQuestion as given (no cleaning): any of
+    # its members (kind:, approval:, …); a key it doesn't have raises
+    # ArgumentError.
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
     # @param watch [#call, nil] asked every WATCH_INTERVAL seconds while the
     #   question waits (outside the lock): a String closes the question with
@@ -155,7 +160,7 @@ module Samagotchi
     # @param on_superseded_close [#call, nil] called when a question that
     #   superseded it closes (its poster posts it again if it still
     #   stands); nil: posted again as it was
-    # @return [Hash, nil] the pending question; nil when it waits for another
+    # @return [PendingQuestion, nil] the pending question; nil when it waits for another
     def post(fields, on_answer:, on_superseded_close: nil)
       standing = { fields: fields, on_answer: on_answer, on_superseded_close: on_superseded_close }
       shelved = @lock.synchronize do
@@ -179,7 +184,7 @@ module Samagotchi
       withdrawn = @lock.synchronize do
         @shelved = nil if id.nil?
         standing = @standing
-        next nil unless standing && @pending && @pending[:id] == standing[:id]
+        next nil unless standing && @pending && @pending.id == standing[:id]
         next nil if id && standing[:id].to_s != id.to_s
 
         @standing = nil
@@ -195,7 +200,7 @@ module Samagotchi
 
     private def ask(fields, watch)
       pending = publish(fields)
-      id = pending[:id]
+      id = pending.id
 
       # If a synchronous UI handler is registered (TUI), invoke it inline on the
       # SAME thread that called request_question (TerminalUI's REPL thread is the
@@ -204,7 +209,7 @@ module Samagotchi
       # any future UI that registers a sync handler gets the same guarantee.
       if @sync_handler
         begin
-          sync_res = @sync_handler.call(pending.dup)
+          sync_res = @sync_handler.call(pending.to_h)
           # Handler may have called answer_question or returned a hash/string.
           # Decided under the lock; saved and announced after it (never emit
           # holding the question lock: a snapshot holds the event lock and
@@ -298,12 +303,12 @@ module Samagotchi
       answer = @lock.synchronize do
         pending = @pending
         raise NotPending, "no pending question" unless pending
-        raise NotPending, "id mismatch" unless pending[:id].to_s == id.to_s
+        raise NotPending, "id mismatch" unless pending.id.to_s == id.to_s
         # First responder wins: after the first answer the turn thread clears
         # @pending in a later lock block, so a second UI's answer can
         # land in between and must not overwrite the first.
         raise NotPending, "question already answered" if @answer
-        raise NotPending, "question #{pending[:status]}" unless pending[:status].to_s == "pending"
+        raise NotPending, "question #{pending.status}" unless pending.status.to_s == "pending"
 
         answer = validated_answer(pending, sel, fm, parent_agent: parent_agent, parent_setting: parent_setting)
         if parent_agent && (reason = Guardrails::ParentContinue.refusal(pending, sel, allowed: parent_continue))
@@ -338,15 +343,15 @@ module Samagotchi
     def annotate(id, relayed_to:, reason: nil)
       marked = @lock.synchronize do
         pending = @pending
-        next nil unless pending && pending[:id].to_s == id.to_s
-        next nil if @answer || pending[:status].to_s != "pending"
+        next nil unless pending && pending.id.to_s == id.to_s
+        next nil if @answer || pending.status.to_s != "pending"
 
-        relayed_to ? pending[:relayed_to] = relayed_to : pending.delete(:relayed_to)
+        @pending = pending = pending.with(relayed_to: relayed_to)
         if session
-          session.pending_question = pending.dup
+          session.pending_question = pending
           begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
         end
-        pending[:id]
+        pending.id
       end
       return false unless marked
 
@@ -372,16 +377,16 @@ module Samagotchi
       cancelled_id = @lock.synchronize do
         pending = @pending
         next unless pending
-        next if id && pending[:id].to_s != id.to_s
-        next if @answer || pending[:status].to_s != "pending"
+        next if id && pending.id.to_s != id.to_s
+        next if @answer || pending.status.to_s != "pending"
         # Its poster closes it; nothing waits on a cancel.
-        raise NotDismissable, "answer #{Array(pending[:options]).join(" or ")}" if @standing && id
+        raise NotDismissable, "answer #{Array(pending.options).join(" or ")}" if @standing && id
         next if @standing
 
-        pending[:status] = "cancelled"
+        @pending = pending.with(status: "cancelled")
         @cancel_reason = reason.to_s
         @cv.broadcast
-        pending[:id]
+        pending.id
       end
       return id.nil? && self.pending.nil? unless cancelled_id
 
@@ -420,21 +425,23 @@ module Samagotchi
     # :question_requested to every UI. Observers that stash the event (e.g.
     # TerminalUI handle_question_event) discard it as stale if a sync
     # handler answers and clears it first (drain_pending_question?).
-    # @return [Hash] the pending question
+    # The event carries it as a Hash (PendingQuestion#to_h), as every UI
+    # and the Bridge's stream read it.
+    # @return [PendingQuestion] the pending question
     # @param standing [Hash, nil] a standing question's record (#post)
     def publish(fields, standing: nil)
-      pending = { id: SecureRandom.uuid, **fields, status: "pending", created_at: Time.now.iso8601(3) }.compact
+      pending = PendingQuestion.new(id: SecureRandom.uuid, **fields, status: "pending", created_at: Time.now.iso8601(3))
       @lock.synchronize do
         @pending = pending
         @answer = nil
         @cancel_reason = nil
-        @standing = standing&.merge(id: pending[:id])
+        @standing = standing&.merge(id: pending.id)
       end
       if session
-        session.pending_question = pending.dup
+        session.pending_question = pending
         begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
       end
-      event = { type: :question_requested, pending_question: pending }
+      event = { type: :question_requested, pending_question: pending.to_h }
       event[:standing] = true if standing
       emit(event)
       pending
@@ -489,11 +496,11 @@ module Samagotchi
     # @return [Hash] {id:, selected:, freeform:, selected_indices:, by:}
     # @raise [ArgumentError, Refused]
     def validated_answer(pending, sel, fm, parent_agent:, parent_setting:)
-      opts = Array(pending[:options])
+      opts = Array(pending.options)
       invalid = sel.reject { |v| opts.include?(v) }
       raise ArgumentError, "invalid selection: #{invalid.join(", ")} (valid: #{opts.join(", ")})" unless invalid.empty?
-      raise ArgumentError, "single-select question: got #{sel.size} selections" if !pending[:multi_select] && sel.size > 1
-      raise ArgumentError, "selection required" if pending[:multi_select] == false && sel.empty? && fm.nil?
+      raise ArgumentError, "single-select question: got #{sel.size} selections" if !pending.multi_select && sel.size > 1
+      raise ArgumentError, "selection required" if pending.multi_select == false && sel.empty? && fm.nil?
 
       indices = sel.map { |v| opts.index(v) }
       # The one whose answer settles the approval (Approval.settle, by index).
@@ -501,7 +508,7 @@ module Samagotchi
         reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: parent_setting)
         raise Refused, reason if reason
       end
-      answer = { id: pending[:id].to_s, selected: sel, freeform: fm, selected_indices: indices.compact }
+      answer = { id: pending.id.to_s, selected: sel, freeform: fm, selected_indices: indices.compact }
       answer[:by] = "parent_agent" if parent_agent
       answer
     end
@@ -513,7 +520,7 @@ module Samagotchi
       loop do
         done = @lock.synchronize do
           next true if @answer || cancel_controller&.cancelled?
-          next true if @pending.nil? || @pending[:status] != "pending"
+          next true if @pending.nil? || @pending.status != "pending"
 
           # Wait with timeout to check cancel; 0.2s matches reminder poll
           @cv.wait([0.2, watch ? next_watch - monotonic : 0.2].min.clamp(0.0, 0.2))
@@ -527,9 +534,9 @@ module Samagotchi
         next unless reason
 
         closed = @lock.synchronize do
-          next false if @answer || @pending.nil? || @pending[:status] != "pending"
+          next false if @answer || @pending.nil? || @pending.status != "pending"
 
-          @pending[:status] = "cancelled"
+          @pending = @pending.with(status: "cancelled")
           true
         end
         return reason if closed

data/lib/samagotchi/relay.rb

@@ -18,29 +18,28 @@ module Samagotchi
     module_function
 
     # @param child [Session] the child as loaded (its id, its first prompt)
-    # @param pending [Hash] the child's pending question (string keys inside
-    #   when it came from a saved session)
+    # @param pending [PendingQuestion] the child's pending question (string
+    #   keys inside its approval and relay when it came from a saved session)
     # @param relay_id [String] RelayDesk's id
     # @param more [Integer] other delegates' approvals waiting behind this one
     # @return [Hash] Engine#open_question fields
     def card(child, pending, relay_id:, more: 0)
-      pending = deep_symbolize(pending)
-      facts = pending[:approval].is_a?(Hash) ? pending[:approval] : {}
+      facts = pending.approval.is_a?(Hash) ? deep_symbolize(pending.approval) : {}
       short = child.id.to_s[0, 8]
-      inner = pending[:relay].is_a?(Hash) ? pending[:relay] : nil
+      inner = pending.relay.is_a?(Hash) ? deep_symbolize(pending.relay) : nil
       chain = inner ? [*Array(inner[:chain]), short] : [short]
-      asked = inner ? inner[:asked].to_s : pending[:question].to_s
+      asked = inner ? inner[:asked].to_s : pending.question.to_s
       task = inner ? inner[:task].to_s : task_of(child)
       who = chain.reverse.join(" → ")
       {
         question: question_text(who, task, asked),
-        options: relabel(Array(pending[:options]), facts[:scopes], who),
+        options: relabel(Array(pending.options), facts[:scopes], who),
         header: header(who, more),
         multi_select: false,
-        allow_freeform: pending.key?(:allow_freeform) ? !!pending[:allow_freeform] : true,
+        allow_freeform: pending.allow_freeform.nil? || !!pending.allow_freeform,
         kind: Guardrails::Approval::KIND,
         approval: facts,
-        relay: { id: relay_id, child_id: child.id, child_short: short, child_question_id: pending[:id].to_s,
+        relay: { id: relay_id, child_id: child.id, child_short: short, child_question_id: pending.id.to_s,
                  task: task, chain: chain, asked: asked, more: more.to_i }
       }
     end