samagotchi 0.124.0 → 0.126.0

data/lib/samagotchi/terminal_ui/exit_lines.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "../tools/task_record"
+
+module Samagotchi
+  class TerminalUI
+    # The /exit ask and its reply lines: pure text from a reply, holds, and
+    # the invocation used to spell commands.
+    module ExitLines
+      module_function
+
+      # Why a request the Bridge read after its deadline didn't go through.
+      LATE = "worker not answering in time"
+      # An exit the worker agreed to in an empty session. Said before it has
+      # left: it checks again once it lets go, and a note or prompt arriving
+      # first keeps the session (SessionManager.discard_left_session).
+      EMPTY_WORDS = "the session is empty: it will be discarded if nothing arrives before its worker stops."
+      EMPTY_EXIT = "Detached; #{EMPTY_WORDS}"
+      # Why the worker stayed up after /exit, by the reason it gave.
+      HELD_REASONS = {
+        "turn_running" => "a turn is running", "input_queued" => "prompts are queued",
+        "continue_offered" => "a continue offer is pending", "client_connected" => "another UI is attached",
+        "reminders" => "reminders are set", "starting" => "the worker is still starting",
+        "background_tasks" => "background tasks it started are still running",
+        "delegates" => "delegates of this session are still running"
+      }.freeze
+      # How to end a background task that holds the worker up (an older
+      # worker's 409 has no hint of its own).
+      TASK_STOP_HINT = "stop one with the web's stop-task button or by asking for task_stop"
+      # The /exit ask, when every hold is one the user can stop: what still
+      # runs, then the three answers. Each kind, singular and plural.
+      EXIT_HOLD_WORDS = {
+        "reminders" => %w[reminder reminders],
+        "background_tasks" => ["background task", "background tasks"],
+        "delegates" => %w[delegate delegates]
+      }.freeze
+      # The 200's +stopped+ keys, by the kind the ask lists them under.
+      STOPPED_KEYS = { "reminders" => "reminders", "tasks" => "background_tasks", "delegates" => "delegates" }.freeze
+      EXIT_ASK_OPTIONS = ["Keep running in the background (detach)", "Stop them and exit", "Back to the session"].freeze
+      # How the ask reads an answer.
+      EXIT_ANSWERS = {
+        "1" => :keep, "keep" => :keep, "detach" => :keep, "background" => :keep,
+        "2" => :stop, "stop" => :stop, "exit" => :stop,
+        "3" => :back, "back" => :back, "stay" => :back
+      }.freeze
+
+      # The ask: what still runs, then the three answers.
+      def ask_lines(holds)
+        lines = holds.map do |hold|
+          items = Array(hold["items"])
+          singular, plural = hold_words(hold["kind"])
+          "  • #{items.size} #{items.size == 1 ? singular : plural}: #{items.map { |item| item_word(item, hold["kind"]) }.join(", ")}"
+        end
+        lines += EXIT_ASK_OPTIONS.each_with_index.map { |option, index| "  #{index + 1}. #{option}" }
+        (["This session still has:"] + lines).join("\n")
+      end
+
+      # One entry of a hold: the command or name, with its detail in
+      # brackets; a delegate leads with its short id and its title in quotes.
+      def item_word(item, kind)
+        label = item["label"].to_s
+        label = "#{item["id"].to_s[0, 8]} \"#{label}\"" if kind == "delegates"
+        detail = item["detail"].to_s
+        detail.empty? ? label : "#{label} (#{detail})"
+      end
+
+      # 1: detach, everything left running.
+      def kept_line(holds, via:, session_id:)
+        "Detached; the session keeps running (#{hold_words_list(holds)}). " \
+          "Re-attach with: #{via.attach(session_id)}"
+      end
+
+      # "2 reminders, 1 background task, 1 delegate" from the ask's holds.
+      def hold_words_list(holds)
+        holds.map do |hold|
+          items = Array(hold["items"])
+          singular, plural = hold_words(hold["kind"])
+          "#{items.size} #{items.size == 1 ? singular : plural}"
+        end.join(", ")
+      end
+
+      def hold_words(kind) = EXIT_HOLD_WORDS.fetch(kind.to_s, [kind.to_s, kind.to_s])
+
+      # What a stop-all exit stopped: "stopped 2 reminders (api_health, git
+      # push), 1 background task (rails s)"; nil when it stopped nothing.
+      def stopped_words(stopped)
+        return nil unless stopped.is_a?(Hash)
+
+        parts = STOPPED_KEYS.filter_map do |key, kind|
+          names = Array(stopped[key])
+          next if names.empty?
+
+          singular, plural = hold_words(kind)
+          "#{names.size} #{names.size == 1 ? singular : plural} (#{names.join(", ")})"
+        end
+        parts.empty? ? nil : "stopped #{parts.join(", ")}"
+      end
+
+      def exit_line(reply, via:, session_id:)
+        error = reply.json&.fetch("error", nil)
+        case reply.status
+        when 200
+          stopped = stopped_words(reply.json&.fetch("stopped", nil))
+          return EMPTY_EXIT if discards?(reply) && stopped.nil?
+          return "Detached; #{stopped}. #{EMPTY_WORDS.capitalize}" if discards?(reply)
+
+          "Detached; #{stopped || "the session's worker is stopping"}. Resume with: #{via.resume(session_id)}"
+        when 409
+          reason = reply.json&.fetch("reason", nil).to_s
+          "Detached; the session keeps running (#{held_words(reason, reply.json&.fetch("tasks", nil))}). " \
+            "Re-attach with: #{via.attach(session_id)}"
+        when 0 then exit_failed_line("no reply", via: via, session_id: session_id)
+        when 408 then exit_failed_line(LATE, via: via, session_id: session_id)
+        else
+          # A worker from before the route answers the Bridge's plain 404.
+          if error == "not_found"
+            return "Detached; this worker runs an older chi and can't be stopped from here: #{via.command("sessions stop #{session_id}")}"
+          end
+
+          exit_failed_line([reply.status, reply.json&.fetch("detail", nil) || error].compact.join(" "),
+                           via: via, session_id: session_id)
+        end
+      end
+
+      # Why the worker stayed up; the background tasks it waits for by
+      # their short id and command (a finish wake's, D3), and how to stop one.
+      def held_words(reason, tasks)
+        words = HELD_REASONS.fetch(reason, reason)
+        listed = Array(tasks).filter_map { |t| "#{Tools::TaskRecord.short_id(t["id"])} (#{t["command"]})" if t.is_a?(Hash) }
+        listed.empty? ? words : "#{words}: #{listed.join(", ")}; #{TASK_STOP_HINT}"
+      end
+
+      # An older worker leaves the field out.
+      def discards?(reply) = reply.json&.fetch("discard", nil) == true
+
+      def exit_failed_line(why, via:, session_id:)
+        "Detached (could not ask the worker to stop: #{why}). Re-attach with: #{via.attach(session_id)}"
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/join_replay.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require_relative "../context_note"
+require_relative "../image_store"
+require_relative "../log"
+require_relative "../message_parts"
+require_relative "../output_formatter"
+require_relative "../steer"
+require_relative "../tool_activity"
+require_relative "../tool_view"
+require_relative "../turn_note"
+require_relative "event_renderer"
+require_relative "formatting"
+
+module Samagotchi
+  class TerminalUI
+    # Draws the saved part of a worker snapshot when an attached TUI joins or
+    # resyncs. The live loop owns the collaborators; this owns replay only.
+    class JoinReplay
+      include Formatting
+
+      # How much of the last answer a join shows.
+      JOIN_ANSWER_LINES = 12
+      JOIN_ANSWER_CHARS = 1200
+
+      def initialize(screen:, view:, link:, gaps:, renderer:)
+        @screen = screen
+        @view = view
+        @link = link
+        @gaps = gaps
+        @renderer = renderer
+      end
+
+      def render_join(snapshot, saved)
+        render_join_header(Array(snapshot[:messages]))
+        render_join_gap(snapshot, saved)
+      end
+
+      # The snapshot's cards and between-turns notices (Bridge CardStore):
+      # on join the ones since the last turn (and the running turn's), as
+      # the join header shows the last exchange; on a resync only cards not
+      # shown here yet, and not the ones an earlier worker saved (a resync
+      # onto a new worker: earlier turns, not news). A turn's own rows (notices, retries) are left out:
+      # the running turn's come with its parts, and the join shows no older
+      # turn's steps.
+      def render_snapshot_cards(entries, joining:)
+        entries.each do |entry|
+          case entry[:type].to_s
+          when "hook_notice"
+            next if entry[:in_turn]
+
+            @screen.commit(EventRenderer.hook_notice_line(entry)) if joining && entry[:turns_since].to_i.zero?
+          when "card"
+            next unless joining ? entry[:turns_since].to_i.zero? : !entry[:earlier] && !@renderer.card_shown?(entry[:id])
+
+            @renderer.render_card(entry, updated: entry[:updated] == true)
+          end
+        end
+      end
+
+      private
+
+      # Where the session's last activity was: its newest stamped entry,
+      # else its saved recap's time. A gap ago (and no turn running): one
+      # line after the join block says when.
+      def render_join_gap(snapshot, saved)
+        @gaps.seed(snapshot[:messages], fallback: saved&.dig(:created_at))
+        return if snapshot[:current_turn]
+
+        line = @gaps.join_line
+        @screen.commit(gap_divider(line)) if line
+      end
+
+      def render_join_header(messages)
+        exchange = messages.select { |m| %w[user model assistant].include?(m[:role].to_s) }
+        # The id stays findable: the detach line and chi sessions list show it.
+        Log.session_id = @link.client.session_id
+        Log.info(:attached, "joined", session: @link.client.session_id, messages: exchange.size,
+                                      notes: messages.count { |m| ContextNote.note?(m) })
+        last_user = exchange.rindex { |m| Steer.prompt?(m) }
+        render_join_notes(messages)
+        return unless last_user
+
+        @screen.commit(join_prompt_line(exchange[last_user]))
+        # An image-only turn's text names its images already.
+        unless ImageRef.placeholder_only?(exchange[last_user][:content])
+          Array(exchange[last_user][:images]).each { |ref| @screen.commit(format_image_line(ref)) }
+        end
+        from = messages.index { |m| m.equal?(exchange[last_user]) }
+        render_join_steps(messages, from, durations: join_tool_records(exchange[last_user]))
+        record = @link.saved_turn_record(exchange[last_user][:turn_id] || exchange[last_user]["turn_id"])
+        failed = join_failed_record(record)
+        # 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"], empty[:refusal] || empty["refusal"]))
+        elsif failed
+          # A failed turn whose steps stayed: the line the live view left,
+          # and no step text as if it were the answer (the web keeps a
+          # failed turn's texts as steps too).
+          failure = failed["failure"]
+          @screen.commit(@view.turn_failed_line(failure["summary"] || failure["message"], failed["duration_ms"]))
+          @screen.commit(@view.turn_end_hint(ROLLBACK_HINT)) if failure["kept_steps"]
+        elsif record && record["status"] == "canceled"
+          # A canceled turn (a Stop, Ctrl-C): its line, as live, and no
+          # text it streamed before the cancel as if it were the answer.
+          @screen.commit(@view.turn_canceled_line(record["cancellation_reason"], record["duration_ms"], by: record["cancelled_by"]))
+          @screen.commit(@view.turn_end_hint(ROLLBACK_HINT)) unless record["continue"]
+        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, 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(MessageParts.for_message(m, responses)&.dig(:tools)).each do |part|
+              record = join_record(records, part)
+              duration = record&.dig("duration_ms")
+              @screen.commit(join_tool_line(part, duration_ms: duration.is_a?(Numeric) ? duration : nil,
+                                                  saved_status: record&.dig("status"),
+                                                  auto_allowed: record&.dig("guardrail")))
+            end
+          end
+        end
+      end
+
+      # The prompt's turn's saved tool records (AttachLink: 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)
+        @link.saved_tool_records(prompt[:turn_id] || prompt["turn_id"])
+      end
+
+      # The turn's saved +record+ when it failed with the fields its line is
+      # made of (SessionMetrics#failure_fields), else nil: a completed or
+      # older turn — or one saved before the failure field — draws its
+      # answer as before (a canceled one its line).
+      def join_failed_record(record)
+        return nil unless record && record["status"] == "failed" && record["failure"].is_a?(Hash)
+
+        failure = record["failure"]
+        return nil if failure["summary"].to_s.empty? && failure["message"].to_s.empty?
+
+        record
+      end
+
+      # The saved record of +part+'s call (its duration and status): 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 (as the web's timing.js
+      # takeRecord). nil for a call that left none: it never finished, or a
+      # worker before turn ids saved it.
+      def join_record(records, part)
+        return nil if part[:output].nil?
+
+        at = records.index { |r| r["tool"].to_s == part[:tool].to_s }
+        return nil unless at
+
+        records.shift(at + 1).last
+      end
+
+      # A saved call's row; "no result" for a call the turn never answered
+      # (it ended first). Its status is the saved record's, as live and the
+      # web's reload (a guardrail's "blocked" is no error), else read from
+      # its result (a guardrail's deny text reads blocked too). A record that
+      # System 1 allowed once (+auto_allowed+, its saved {rule, p}) says so,
+      # as the live row does.
+      def join_tool_line(part, duration_ms: nil, saved_status: nil, auto_allowed: nil)
+        output = part[:output]
+        command = part.dig(:view, :truncated) ? nil : part.dig(:view, :command)
+        text = ToolActivity.saved_result_text(output) unless output.nil?
+        status = if output.nil?
+                   "no result"
+                 elsif !saved_status.to_s.empty?
+                   saved_status.to_s
+                 elsif ToolActivity.guardrail_denied?(text)
+                   "blocked"
+                 else
+                   ToolActivity.tool_activity_status(text, part[:tool], command: command)
+                 end
+        activity = { action: part[:label] || ToolActivity.tool_activity_action(part[:tool]), tool: part[:tool],
+                     params: part[:params], status: status,
+                     description: ToolView.description_title(part[:view] || {}) }
+        "#{format_tool_activity_line(activity, duration_ms: duration_ms)}" \
+          "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}#{format_tool_cut_suffix(part[:output_truncated])}" \
+          "#{auto_allowed_suffix(auto_allowed)}"
+      end
+
+      # The live row's System 1 suffix for a saved record's {rule, p}.
+      def auto_allowed_suffix(saved)
+        return "" unless saved.is_a?(Hash)
+
+        format_tool_guardrail_suffix({ decided_by: "system one", p: saved["p"] || saved[:p] })
+      end
+
+      # The context notes that came since the last prompt (all of them in a
+      # session with none), after the exchange the header shows.
+      def render_join_notes(messages, after_exchange: false)
+        last_user = messages.rindex { |m| Steer.prompt?(m) }
+        return if after_exchange != !last_user.nil?
+
+        messages[(last_user ? last_user + 1 : 0)..].select { |m| ContextNote.note?(m) }.each do |m|
+          @screen.commit(context_note_line(ContextNote.label_of(m), ContextNote.text_of(m)))
+        end
+      end
+
+      # The end of a long answer; the whole of it is in the session.
+      def last_lines(text)
+        lines = text.split("\n", -1)
+        if lines.size > JOIN_ANSWER_LINES
+          text = "(… #{lines.size - JOIN_ANSWER_LINES} earlier lines)\n#{lines.last(JOIN_ANSWER_LINES).join("\n")}"
+        end
+        return text if text.length <= JOIN_ANSWER_CHARS
+
+        "(… earlier text)\n…#{text[-JOIN_ANSWER_CHARS..]}"
+      end
+    end
+  end
+end

data/lib/samagotchi/verdict.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A parsed verdict line from a Verify turn's final answer.
+  Verdict = Data.define(:verdict, :reason) do
+    LINE = /\AVerdict:\s*(confirmed|refuted|unclear)\b\s*(?:—|–|-)\s*(.+?)\s*\z/i
+    MARKDOWN = /(?:\*\*|__|`)/
+
+    def self.parse(text)
+      line = text.to_s.lines.reverse_each.find { |candidate| !candidate.strip.empty? }
+      return unless line
+
+      normalized = line.strip.gsub(MARKDOWN, "")
+      match = LINE.match(normalized)
+      return unless match
+
+      new(verdict: match[1].downcase, reason: match[2].strip)
+    end
+  end
+end

data/lib/samagotchi/verify_anchor.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+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)
+
+      fields = value.to_h { |key, entry| [key.to_s, entry] }
+      return nil unless fields.keys.sort == %w[quote turn_id]
+
+      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?
+
+      new(turn_id:, quote:)
+    end
+
+    def to_h = { turn_id:, quote: }
+
+    def to_file = { "turn_id" => turn_id, "quote" => quote }
+  end
+end