samagotchi 0.75.0 → 0.77.0

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -141,7 +141,8 @@ module Samagotchi
           name: BUNDLE_NAME,
           scope: SCOPE,
           force: false,
-          strict: true
+          strict: true,
+          shipped_dir: File.dirname(GEM_BUNDLE_DIR)
         )
         installer.run
         result(:installed, to: to, warnings: installer.warnings)
@@ -182,7 +183,8 @@ module Samagotchi
       end
 
       def upgrade_installer
-        Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true)
+        Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true,
+                      shipped_dir: File.dirname(GEM_BUNDLE_DIR))
       end
       private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present,
                            :upgrade_installer, :result, :conflicting

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/model_price.rb

@@ -37,9 +37,10 @@ module Samagotchi
     # USD for one generation, OpenAI usage semantics: +prompt_tokens+ holds
     # the cached reads and the cache writes (OpenRouter keeps that for
     # Anthropic models), and reasoning is inside +completion_tokens+.
-    # llama.cpp's native timings.prompt_n leaves its cache_n out, so the
-    # uncached part is clamped at 0: an undercount, harmless because priced
-    # models are remote.
+    # llama.cpp's native stream ends with tokens_evaluated, the whole prompt
+    # (SessionMetrics keeps the largest count, so not timings.prompt_n,
+    # which leaves cache_n out); the uncached part is clamped at 0 for a
+    # report that has prompt_n alone.
     def cost(prompt_tokens:, cached_tokens:, cache_write_tokens:, completion_tokens:)
       uncached = (prompt_tokens - cached_tokens - cache_write_tokens).clamp(0..)
       ((uncached * input) + (cached_tokens * cache_read) + (cache_write_tokens * cache_write) +

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/paths.rb

@@ -28,7 +28,21 @@ module Samagotchi
     # @return [String] $XDG_CONFIG_HOME (absolute), else ~/.config
     def config_home(env: ENV)
       xdg = env.fetch("XDG_CONFIG_HOME", "").to_s.strip
-      xdg.empty? ? File.expand_path("~/.config") : File.absolute_path(xdg)
+      xdg.empty? ? File.join(Dir.home, ".config") : File.absolute_path(xdg)
+    end
+
+    # The set XDG dirs, made absolute. +set+ is :nonblank (unset or blank
+    # values omitted) or :key (present keys included, even when blank).
+    # @return [Hash{String => String}]
+    def absolute_xdg(env: ENV, set: :nonblank)
+      included = case set
+                 when :nonblank then ->(key) { !env.fetch(key, "").to_s.strip.empty? }
+                 when :key then ->(key) { env.key?(key) }
+                 else raise ArgumentError, "set must be :nonblank or :key"
+                 end
+      { "XDG_STATE_HOME" => :state_home, "XDG_CONFIG_HOME" => :config_home }.each_with_object({}) do |(key, home), dirs|
+        dirs[key] = public_send(home, env: env) if included.call(key)
+      end
     end
 
     # +path+ as chi shows it: ~ for the home folder (~/a for one in it),

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