samagotchi 0.134.0 → 0.136.0

data/lib/samagotchi/tools/delegate_relay.rb

@@ -192,7 +192,7 @@ module Samagotchi
       # of a relay), else its hook; an approval's call (#what_text).
       # @param question [PendingQuestion] the child's
       def what(question)
-        return what_text(symbolized(question.approval)) unless question.kind.to_s == HOOK_KIND
+        return what_text(Guardrails::ApprovalFacts.from_h(question.approval)) unless question.kind.to_s == HOOK_KIND
 
         inner = symbolized(question.relay, nil)
         header = (inner ? inner[:header] : question.header).to_s
@@ -204,11 +204,12 @@ module Samagotchi
       end
 
       # execute: git push origin main
+      # @param facts [Guardrails::ApprovalFacts, nil] the saved card's
       def what_text(facts)
-        facts = {} unless facts.is_a?(Hash)
-        tool = facts[:label] || facts[:tool] || "tool"
-        what = facts[:command] || Array(facts[:paths]).join(", ")
-        what = facts[:args].to_s if what.to_s.empty?
+        facts ||= Guardrails::ApprovalFacts.new
+        tool = facts.label || facts.tool || "tool"
+        what = facts.command || Array(facts.paths).join(", ")
+        what = facts.args.to_s if what.to_s.empty?
         what.to_s.empty? ? tool.to_s : "#{tool}: #{what}"
       end
 

data/lib/samagotchi/tools/delegate_wait.rb

@@ -337,13 +337,13 @@ module Samagotchi
           "truncated=true",
           "preview_strategy=head_tail",
           "reply_bytes=#{text.bytesize}",
-          "returned_preview_bytes=#{preview[:returned_preview_bytes]}",
-          "omitted_bytes=#{preview[:omitted_bytes]}",
+          "returned_preview_bytes=#{preview.returned_preview_bytes}",
+          "omitted_bytes=#{preview.omitted_bytes}",
           "[TRUNCATED_PREVIEW_HEAD]",
-          preview[:head],
-          "[... omitted #{preview[:omitted_bytes]} bytes ...]",
+          preview.head,
+          "[... omitted #{preview.omitted_bytes} bytes ...]",
           "[TRUNCATED_PREVIEW_TAIL]",
-          preview[:tail]
+          preview.tail
         ].join("\n")
       end
     end

data/lib/samagotchi/tools/execute.rb

@@ -469,13 +469,13 @@ module Samagotchi
           "truncated=true",
           "preview_strategy=head_tail",
           "#{label}_bytes=#{bytes}",
-          "returned_preview_bytes=#{preview[:returned_preview_bytes]}",
-          "omitted_bytes=#{preview[:omitted_bytes]}",
+          "returned_preview_bytes=#{preview.returned_preview_bytes}",
+          "omitted_bytes=#{preview.omitted_bytes}",
           "[TRUNCATED_PREVIEW_HEAD]",
-          preview[:head],
-          "[... omitted #{preview[:omitted_bytes]} bytes ...]",
+          preview.head,
+          "[... omitted #{preview.omitted_bytes} bytes ...]",
           "[TRUNCATED_PREVIEW_TAIL]",
-          preview[:tail]
+          preview.tail
         ].join("\n")
       end
 
@@ -492,7 +492,7 @@ module Samagotchi
       # A big log: its size, and the head and tail read by seek, which
       # output_block shows as it shows a long string's.
       class LogPreview
-        attr_reader :bytesize, :preview
+        attr_reader :bytesize, :preview # Integer, OutputGuardrails::PreviewParts
 
         def initialize(bytesize, preview)
           @bytesize = bytesize

data/lib/samagotchi/tools/output_guardrails.rb

@@ -11,6 +11,11 @@ module Samagotchi
       DEFAULT_TELEMETRY_THRESHOLD_PCT = 80.0
       DEFAULT_CHARS_PER_TOKEN = 4.0
 
+      # A large output's head and tail (UTF-8 safe) with the byte counts the
+      # truncated-preview result lines report.
+      PreviewParts = Data.define(:head, :tail, :head_bytes, :tail_bytes, :returned_preview_bytes,
+                                 :omitted_bytes, :total_bytes)
+
       module_function
 
       # The config setting +key+ (read.*, execute.*, context.*) when positive, else +default+.
@@ -41,6 +46,7 @@ module Samagotchi
              .encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")
       end
 
+      # @return [PreviewParts]
       def head_tail_from_file(path:, file_size:, preview_bytes:)
         half = [preview_bytes / 2, 1].max
         head = File.binread(path, half, 0)
@@ -50,6 +56,7 @@ module Samagotchi
         build_preview_parts(head: head, tail: tail, total_bytes: file_size)
       end
 
+      # @return [PreviewParts]
       def head_tail_from_string(content:, preview_bytes:)
         half = [preview_bytes / 2, 1].max
         head = content.byteslice(0, half) || ""
@@ -78,7 +85,7 @@ module Samagotchi
         tail_bytes = tail.bytesize
         omitted_bytes = [total_bytes - (head_bytes + tail_bytes), 0].max
 
-        {
+        PreviewParts.new(
           head: safe_utf8(head),
           tail: safe_utf8(tail),
           head_bytes: head_bytes,
@@ -86,7 +93,7 @@ module Samagotchi
           returned_preview_bytes: head_bytes + tail_bytes,
           omitted_bytes: omitted_bytes,
           total_bytes: total_bytes
-        }
+        )
       end
       private_class_method :build_preview_parts
     end

data/lib/samagotchi/tools/read.rb

@@ -81,10 +81,10 @@ module Samagotchi
 
         preview_block = [
           "[TRUNCATED_PREVIEW_HEAD]",
-          preview[:head],
-          "[... omitted #{preview[:omitted_bytes]} bytes ...]",
+          preview.head,
+          "[... omitted #{preview.omitted_bytes} bytes ...]",
           "[TRUNCATED_PREVIEW_TAIL]",
-          preview[:tail]
+          preview.tail
         ].join("\n")
 
         metadata_lines = [
@@ -92,8 +92,8 @@ module Samagotchi
           "path=#{path}",
           "preview_strategy=head_tail",
           "file_bytes=#{file_size}",
-          "returned_preview_bytes=#{preview[:returned_preview_bytes]}",
-          "omitted_bytes=#{preview[:omitted_bytes]}"
+          "returned_preview_bytes=#{preview.returned_preview_bytes}",
+          "omitted_bytes=#{preview.omitted_bytes}"
         ]
 
         telemetry = telemetry_lines_for(preview_block)

data/lib/samagotchi/turn_anchors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "revise_anchor"
+require_relative "verify_anchor"
+
+module Samagotchi
+  # What a turn points at in an earlier turn: a Verify turn's claim
+  # (VerifyAnchor) and a Revise turn's draft (ReviseAnchor). One carrier
+  # through every layer a turn's input travels (chi web's POST /turn, the
+  # Bridge, the input file, SessionInbox::Input, WorkerInbound::Prompt, a
+  # failed turn's restore), so a new anchor is one field here. On the wire
+  # and in the input file each is its own key ("verify", "revises"); a
+  # missing or malformed one is nil. The Engine takes them as run_turn's
+  # keywords (#kwargs): what each means is its own.
+  TurnAnchors = Data.define(:verify, :revises) do
+    def self.from(value)
+      return value if value.is_a?(self)
+
+      fields = value.is_a?(Hash) ? value.to_h { |key, entry| [key.to_s, entry] } : {}
+      new(verify: fields["verify"], revises: fields["revises"])
+    end
+
+    # Whether a parsed input file names an anchor (a Hash under its key,
+    # well-formed or not): SessionInbox.turn_end_data? holds it.
+    def self.named_in?(data) = %w[verify revises].any? { |key| data[key].is_a?(Hash) }
+
+    def initialize(verify: nil, revises: nil)
+      super(verify: VerifyAnchor.from(verify), revises: ReviseAnchor.from(revises))
+    end
+
+    def empty? = verify.nil? && revises.nil?
+
+    # The anchors given, each answering FEATURE (the worker's Bridge
+    # feature it needs) and UNAVAILABLE (the refusal without it).
+    def present = [verify, revises].compact
+
+    # The body's and the input file's keys.
+    def to_file = { "verify" => verify&.to_file, "revises" => revises&.to_file }.compact
+
+    # A :prompt_restored event's fields.
+    def to_h = { verify: verify&.to_h, revises: revises&.to_h }.compact
+
+    # Engine#run_turn's keywords.
+    def kwargs = { verify:, revises: }.compact
+
+    # A participant's: they can't Revise (participant_access.rb, the Bridge).
+    def without_revises = with(revises: nil)
+  end
+end

data/lib/samagotchi/verify_anchor.rb

@@ -3,9 +3,6 @@
 module Samagotchi
   # A claim selected in an earlier turn, carried only by a Verify turn.
   VerifyAnchor = Data.define(:turn_id, :quote) do
-    UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
-    QUOTE_MAX = 200
-
     def self.from(value)
       return value if value.is_a?(self)
       return nil unless value.is_a?(Hash)
@@ -15,8 +12,8 @@ module Samagotchi
 
       turn_id = fields["turn_id"]
       quote = fields["quote"]
-      return nil unless turn_id.is_a?(String) && UUID.match?(turn_id)
-      return nil unless quote.is_a?(String) && quote.length.between?(1, QUOTE_MAX) && !quote.strip.empty?
+      return nil unless turn_id.is_a?(String) && self::UUID.match?(turn_id)
+      return nil unless quote.is_a?(String) && quote.length.between?(1, self::QUOTE_MAX) && !quote.strip.empty?
 
       new(turn_id:, quote:)
     end
@@ -26,6 +23,9 @@ module Samagotchi
     def to_file = { "turn_id" => turn_id, "quote" => quote }
   end
 
+  # The shape of the turn id an anchor names (ReviseAnchor's too).
+  VerifyAnchor::UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+  VerifyAnchor::QUOTE_MAX = 200
   VerifyAnchor::FEATURE = "verify"
   VerifyAnchor::UNAVAILABLE = {
     "error" => "verify_unavailable",

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.134.0"
+  VERSION = "0.136.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -134,8 +134,6 @@ module Samagotchi
 
       # @param bridge_wait_timeout [Float] bounded seconds to wait for a
       #   freshly-spawned worker's bridge before answering POST /api/sessions.
-      # @param view ["stage", "turn"] the page's view of a turn (web.view);
-      #   ?view=stage|turn overrides it for one page load
       # @param working_set [Boolean] the stage view's working set
       #   (web.working_set); ?working_set=1|0 overrides it for one page load
       # @param annotate_presets [String, Array] the quick replies next to
@@ -168,7 +166,7 @@ module Samagotchi
       # @param start_dir [String] the folder chi web starts in (StartDir):
       #   where a new session without a dir starts (nil: the cwd)
       def initialize(manager: nil, session_class: nil, state_dir: nil, public_dir: nil,
-                     bridge_wait_timeout: BRIDGE_WAIT_TIMEOUT, markdown: false, view: Config::BY_KEY["web.view"].default, hub: nil,
+                     bridge_wait_timeout: BRIDGE_WAIT_TIMEOUT, markdown: false, hub: nil,
                      annotate_presets: Config::BY_KEY["web.annotate_presets"].default,
                      editor: Config::BY_KEY["web.editor"].default,
                      events_heartbeat: EVENTS_HEARTBEAT, events_queue: EVENTS_QUEUE,
@@ -188,7 +186,6 @@ module Samagotchi
         @public_dir = public_dir || File.expand_path("public", __dir__)
         @bridge_wait_timeout = bridge_wait_timeout
         @markdown_renderer = MarkdownRenderer.new(enabled: markdown)
-        @view = view
         @working_set = working_set
         @annotate_presets = annotate_presets.is_a?(Array) ? annotate_presets.join("|") : annotate_presets.to_s
         @editor_url = Editor.template(editor)
@@ -1292,7 +1289,7 @@ module Samagotchi
         nil
       end
 
-      # The LLM context +model+ starts under (the start page's llm ctx chip);
+      # The LLM context +model+ starts under (the start page's ⚙ panel);
       # one that can't be read leaves this model without, not the others.
       def add_llm_context(model, target, names, settings)
         model[:llm_context] = LLMContextStrategy.explain(target, names: names, models: settings).summary(nil)
@@ -1301,7 +1298,7 @@ module Samagotchi
       end
 
       # The thinking level +model+ starts at, with where it came from (the
-      # start page's think chip; SettingExplained#summary, no session).
+      # start page's ⚙ panel; SettingExplained#summary, no session).
       def add_thinking(model, target, names, settings)
         model[:thinking] = Thinking.explain(target, names: names, models: settings).summary
       rescue StandardError
@@ -1476,7 +1473,7 @@ module Samagotchi
       # set when it seeds a session's and when the expanded view opens (a
       # file changed while the session sat idle). A live worker's snapshot
       # messages are the truth, as #handle_show's, else the file's; the
-      # strategy is the session's llm ctx chip's, the folder its working
+      # strategy is the session's llm_context summary's, the folder its working
       # directory. running: a turn runs. The snapshot's messages lag it, so
       # the answer is then the turn's last :working_set_updated (the
       # snapshot's working_set, TurnAccumulator#working_set); before the
@@ -1509,7 +1506,7 @@ module Samagotchi
         { items: set["items"], at: set["at"] }
       end
 
-      # The strategy an llm ctx chip names ("none", "stale,forget"), as
+      # The strategy an llm_context summary names ("none", "stale,forget"), as
       # LLMContextView takes it; none when there is no chip.
       def working_set_strategy(llm_context)
         named = llm_context.is_a?(Hash) ? (llm_context[:strategy] || llm_context["strategy"]).to_s : ""
@@ -2015,8 +2012,7 @@ module Samagotchi
         # The owner's home: a claim link's quote reads it "~", as the
         # participant page shows it (claim_link.js).
         attrs["home"] = Dir.home
-        attrs["view"] = view_name(req.params["view"])
-        # Only when on: the page reads its presence (the turn view ignores it).
+        # Only when on: the page reads its presence.
         attrs["working-set"] = "1" if working_set?(req.params["working_set"])
         attrs.merge!(annotate_presets_data)
         dir, = scope_dir(req.params["dir"])
@@ -2060,14 +2056,6 @@ module Samagotchi
         File.directory?(dir) && ProjectScope.root_for(dir) ? dir : nil
       end
 
-      VIEWS = Config::BY_KEY["web.view"].enum_values
-
-      # The view for this page load: ?view=stage|turn wins, anything
-      # else leaves the config's choice (web.view).
-      def view_name(param)
-        VIEWS.include?(param) ? param : @view
-      end
-
       # The working set for this page load: ?working_set=1|0 wins, anything
       # else leaves the config's choice (web.working_set).
       def working_set?(param)

data/lib/samagotchi/web/message_display.rb

@@ -10,6 +10,7 @@ require_relative "../message_time"
 require_relative "../output_formatter"
 require_relative "../recap_store"
 require_relative "../ref"
+require_relative "../revise_anchor"
 require_relative "../steer"
 require_relative "../turn_note"
 require_relative "../bridge/card_store"
@@ -28,9 +29,19 @@ module Samagotchi
       # A POST /api/render body may be this big: a decision message is a few
       # KB, and the cap bounds the work a page can ask for.
       MAX_RENDER_BYTES = 64 * 1024
+      # A delegate report's leading "session: <id>" / "status: <s>" lines
+      # (Tools::DelegateWait.result).
+      REPORT_HEADER = /\A((?:(?:session|status): [^\n]*\n)+)/
 
       private
 
+      # A delegate report's text as the markdown it renders from: its header
+      # lines one to a line and a paragraph of their own, so a "---" after
+      # them is a rule, not a heading's underline.
+      def report_markdown(text)
+        text.sub(REPORT_HEADER) { "#{Regexp.last_match(1).lines.map(&:chomp).join("  \n")}\n\n" }
+      end
+
       # The recap saved with the session and how many user turns came since:
       # a live worker's (it counts against its Engine's messages), else
       # recap.json against the session file. A stopped session gets its
@@ -70,7 +81,7 @@ module Samagotchi
 
       # @param msgs [Array<Hash>] a session's messages; symbol keys from disk,
       #   string keys from a Bridge snapshot
-      # @param parts [Boolean] the turn view's reload (?parts=1): each
+      # @param parts [Boolean] the turn block's reload (?parts=1): each
       #   assistant message also carries what it did (MessageParts: thinking,
       #   tool calls with params and output), and a message with nothing to
       #   show but that (a text-less step) is kept with empty content
@@ -91,6 +102,7 @@ module Samagotchi
             if Samagotchi::Steer.turn_prompt?(m)
               note[:turn_start] = true
               note[:turn_id] = (m[:turn_id] || m["turn_id"]).to_s
+              note.merge!(revises_of(m))
             end
             filtered << note
             next
@@ -130,11 +142,24 @@ module Samagotchi
             message.merge!(merged: true, step: steer_step(list, index)) unless Samagotchi::Steer.turn_prompt?(m)
             source = (m[:source] || m["source"]).to_s
             message[:source] = source unless source.empty?
+            # A delegate report is the child's markdown: rendered as an
+            # answer is (its copy source stays the text). Another user line
+            # stays plain.
+            if source == Samagotchi::Steer::DELEGATE_REPORT && @markdown_renderer.available?
+              message[:html] = @markdown_renderer.render(report_markdown(stripped))
+            end
           end
           # The turn it started (Engine): the page pairs it with that turn's
           # record by this, not by its place.
           turn_id = m[:turn_id] || m["turn_id"]
           message[:turn_id] = turn_id.to_s if norm_role == "user" && turn_id
+          # The turn it revised (a Revise stack, Engine#stamp_opening), and
+          # whether it was a Verify turn (the page offers no Revise on its
+          # answer).
+          if norm_role == "user" && turn_id && !message[:merged]
+            message.merge!(revises_of(m))
+            message[:verify] = true if Samagotchi::VerifyAnchor.from(m[:verify] || m["verify"])
+          end
           # A participant's message names them (the page's author badge).
           if norm_role == "user"
             message.merge!(Samagotchi::Steer.author_fields(m[:author] || m["author"], m[:author_name] || m["author_name"]))
@@ -166,6 +191,13 @@ module Samagotchi
         []
       end
 
+      # A turn opening's Revise stamp as {revises: {turn_id:}}, checked again
+      # (a stored file is never trusted), or nothing.
+      def revises_of(message)
+        anchor = Samagotchi::ReviseAnchor.from(message[:revises] || message["revises"])
+        anchor ? { revises: anchor.to_h } : {}
+      end
+
       # The entry's wall time (MessageTime: the page's hover and gap
       # dividers) as {at:}, or nothing for an entry saved without one.
       def time_of(message)

data/lib/samagotchi/web/participant_access.rb

@@ -272,10 +272,10 @@ module Samagotchi
         reason = participant_turn_refusal(grant, prompt, body)
         return participant_turn_refused(grant, prompt, *reason) if reason
 
-        verify = VerifyAnchor.from(body["verify"])
+        # A Verify turn's claim; never a Revise (the owner's stacks).
         result = SessionManager.deliver_turn(id, prompt: prompt, client_id: ClientId.review(grant.id),
                                                  delivery: Delivery::QUEUE, author: grant.author,
-                                                 verify: verify,
+                                                 anchors: TurnAnchors.from(body).without_revises,
                                                  pending_limit: grant.queue_limit + 1,
                                                  state_dir: @state_dir, manager: @manager,
                                                  bridge: -> { live_bridge_client(id) })

data/lib/samagotchi/web/participant_view.rb

@@ -4,6 +4,7 @@ require_relative "../output_formatter"
 require_relative "../steer"
 require_relative "../turn_origin"
 require_relative "../participant_mode"
+require_relative "../revise_anchor"
 require_relative "../verify_anchor"
 
 module Samagotchi
@@ -134,6 +135,10 @@ module Samagotchi
         out = { "type" => field(event, :type).to_s, **id_fields(event) }
         verdict = verdict_record(field(event, :verdict), viewer)
         out["verdict"] = verdict if verdict
+        # The turn a completed Revise turn revised (as on its prompt; the
+        # page doesn't draw stacks yet).
+        revises = ReviseAnchor.from(field(event, :revises))
+        out["revises"] = revises.to_file if revises
         out
       end
 
@@ -249,6 +254,9 @@ module Samagotchi
         out["content"] = field(message, :content).to_s
         out["turn_id"] = turn_id.to_s if turn_id
         out["merged"] = true if merged
+        # The turn it revised (a Revise stack; the page doesn't draw it yet).
+        revises = ReviseAnchor.from(field(message, :revises))
+        out["revises"] = revises.to_file if revises && turn_id && !merged
         out.merge!(author_fields(field(message, :author), field(message, :author_name), viewer,
                                  field(message, :participant_mode)))
         images = field(message, :images)

data/lib/samagotchi/web/public/activity.js

@@ -154,7 +154,7 @@ export function addCompleted(model, event = {}, now = null) {
       ...(guardrail.judgment_id ? { judgment_id: guardrail.judgment_id } : {}),
     };
   }
-  // The images the tool returned (a reload in the turn view draws them from
+  // The images the tool returned (a reload's turn block draws them from
   // the saved parts, turn_html.js toolRowTemplate).
   if (event.images?.length) row.images = event.images;
   // What an edit/write changed in its file (a reload draws it from the

data/lib/samagotchi/web/public/annotations.js

@@ -27,7 +27,7 @@ export function annotationSource(node) {
   }
   const thinking = el.closest(".thinking-body");
   if (thinking) return { kind: "thinking", root: thinking };
-  // A step's narration in the turn view (the live one streams).
+  // A step's narration in a turn block (the live one streams).
   const step = el.closest(".gen-text");
   if (step) return step.classList.contains("streaming") ? null : { kind: "step", root: step };
   const own = el.closest(".bubble.user .user-message");