samagotchi 0.24.0 → 0.25.0

data/lib/samagotchi/thinking_tails.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "atomic_file"
+
+module Samagotchi
+  # The thinking a session would otherwise lose: a SessionObserver
+  # subscriber (next to SessionMetrics) that keeps the tail of a generation
+  # cut mid-stream (a plugin's stop_generation, loop-guard's cut, a steer's
+  # cut), stopped with its turn by a plugin (stop_turn), or ended at the
+  # provider's output cap (finish_reason length). A cut generation's
+  # thinking is dropped from the conversation, and a looping one is what a
+  # fixture needs.
+  #
+  # The tails go to <session dir>/thinking_tails.jsonl, one JSON record a
+  # line, the newest MAX_RECORDS kept: next to the session's analytics.json,
+  # so an archived session (and a copied session dir) keeps them. Not in the
+  # session's messages (nothing there can reach the model, hooks or the
+  # web's reload by accident) and not in the turn records (the live snapshot
+  # carries those on every /state frame).
+  class ThinkingTails
+    FILE = "thinking_tails.jsonl"
+    # The last chars of a generation's thinking kept: a loop's cycle and
+    # some of its lead-in.
+    TAIL_CHARS = 20_000
+    MAX_RECORDS = 10
+
+    # @param session_dir [#call] the current session's directory, or nil
+    #   (no session yet: nothing is written)
+    def initialize(session_dir:, clock: -> { Time.now })
+      @session_dir = session_dir
+      @clock = clock
+      @turn_id = nil
+      reset
+    end
+
+    # The saved records of +dir+, oldest first (empty without a file).
+    # @return [Array<Hash>] string-keyed
+    def self.read(dir)
+      File.readlines(File.join(dir, FILE), chomp: true).filter_map do |line|
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+    rescue SystemCallError
+      []
+    end
+
+    def call(event)
+      case event[:type]
+      when :turn_started then @turn_id = event[:turn_id]
+      when :generation_started, :generation_retrying then reset
+      when :generation_chunk then add(event[:thinking].to_s)
+      when :generation_completed then completed(event)
+      when :generation_cancelled
+        # A plugin's stop_turn mid-generation; a user's Stop is not kept.
+        keep(event, finish_reason: "cancelled", stopped_by: "hook") if event[:reason].to_s == "hook"
+      end
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def reset
+      @tail = +""
+      @chars = 0
+    end
+
+    def add(thinking)
+      return if thinking.empty?
+
+      @chars += thinking.length
+      @tail << thinking
+      @tail = @tail[-TAIL_CHARS..] if @tail.length > 2 * TAIL_CHARS
+    end
+
+    def completed(event)
+      stopped_by = event[:stopped_by]
+      return reset unless stopped_by || event[:finish_reason].to_s == "length"
+
+      keep(event, finish_reason: event[:finish_reason].to_s, stopped_by: stopped_by&.to_s, stop_reason: event[:stop_reason])
+    end
+
+    # Writes the record and forgets the generation (the native loop's cut
+    # with no retry left reports :generation_cancelled after it too).
+    def keep(event, **fields)
+      return reset if @chars.zero?
+
+      record = { at: @clock.call.utc.iso8601(3), turn_id: @turn_id, iteration: event[:iteration], **fields,
+                 thinking_chars: @chars, tail: @tail.length > TAIL_CHARS ? @tail[-TAIL_CHARS..] : @tail }.compact
+      reset
+      dir = @session_dir.call
+      return unless dir
+
+      FileUtils.mkdir_p(dir)
+      lines = self.class.read(dir).last(MAX_RECORDS - 1).map { |kept| JSON.generate(kept) }
+      AtomicFile.write(File.join(dir, FILE), (lines + [JSON.generate(record)]).join("\n") << "\n")
+    end
+  end
+end

data/lib/samagotchi/token_usage.rb

@@ -12,15 +12,16 @@ module Samagotchi
   # The last chunk can say more: llama.cpp adds a `timings` block with exact
   # speeds and `cache_n` (its native `tokens_cached` counts the new tokens too,
   # so it is not read); OpenRouter adds `usage.cost` (USD) and the
-  # `prompt_tokens_details.cached_tokens` / `completion_tokens_details.reasoning_tokens`
-  # breakdowns. Those fields are nil when a payload doesn't carry them.
+  # `prompt_tokens_details.cached_tokens` / `cache_write_tokens` /
+  # `completion_tokens_details.reasoning_tokens` breakdowns (cache writes:
+  # Anthropic models, prompt caching's first request). Those fields are nil when a payload doesn't carry them.
   #
   # from_payload returns nil when no server token counts are present, so a
   # caller can fall back to a chars/4 heuristic. The reported values are
   # cumulative per request, so callers should take the running MAX across
   # chunks (see SessionMetrics).
-  class TokenUsage < Data.define(:prompt_tokens, :completion_tokens, :cached_tokens, :reasoning_tokens, :cost,
-                                 :predicted_per_second, :prompt_per_second, :predicted_ms, :source)
+  class TokenUsage < Data.define(:prompt_tokens, :completion_tokens, :cached_tokens, :cache_write_tokens,
+                                 :reasoning_tokens, :cost, :predicted_per_second, :prompt_per_second, :predicted_ms, :source)
     CHARS_PER_TOKEN = 4.0
 
     class << self
@@ -41,11 +42,12 @@ module Samagotchi
         )
         return nil unless prompt_tokens || completion_tokens
 
+        details = hash_at(usage, :prompt_tokens_details)
         new(
           prompt_tokens: prompt_tokens,
           completion_tokens: completion_tokens,
-          cached_tokens: first_positive(*both(hash_at(usage, :prompt_tokens_details), :cached_tokens),
-                                        *both(timings, :cache_n)),
+          cached_tokens: first_positive(*both(details, :cached_tokens), *both(timings, :cache_n)),
+          cache_write_tokens: first_positive(*both(details, :cache_write_tokens)),
           reasoning_tokens: first_positive(*both(hash_at(usage, :completion_tokens_details), :reasoning_tokens)),
           cost: number(*both(usage, :cost)),
           predicted_per_second: positive_number(*both(timings, :predicted_per_second)),
@@ -55,6 +57,16 @@ module Samagotchi
         )
       end
 
+      # A request's prompt-cache counts as a :generation_completed event
+      # carries them (the log line too): the prompt, the part of it the
+      # server reused from its cache, and the part it wrote to it (nil when
+      # none: only some remote servers report writes).
+      # @return [Hash] {prompt_tokens:, cached_tokens:, cache_write_tokens:}
+      def cache_fields(prompt:, cached:, cache_write:)
+        { prompt_tokens: prompt.to_i, cached_tokens: cached.to_i,
+          cache_write_tokens: cache_write.to_i.positive? ? cache_write.to_i : nil }
+      end
+
       # Estimate token count from raw text length using the chars/4 heuristic.
       # @param text [String]
       # @return [Integer]

data/lib/samagotchi/tool_activity.rb

@@ -2,6 +2,8 @@
 
 require "json"
 require_relative "log"
+require_relative "command_steps"
+require_relative "tool_view"
 require_relative "tools/execute"
 require_relative "tools/read"
 require_relative "tools/write"
@@ -42,15 +44,34 @@ module Samagotchi
       }
       title = tool_title(tool_name, call, cwd: cwd)
       event[:title] = title if title
+      # The model's own words for a command, which the TUI's tool line
+      # shows in place of the cut params.
+      description = command_description(tool_name, call)
+      event[:description] = description if description
       event
     end
 
+    # An execute's description, cut as a row's title; nil for the rest.
+    def command_description(tool_name, call)
+      return nil unless call.is_a?(Hash) && ToolView::TOOLS.include?(tool_name)
+
+      ToolView.description_title(call)
+    end
+
     # What the call did, for a web row's one line ("edit lib/a.rb", the
     # command without its "cd … &&"): a file tool's path relative to +cwd+
-    # when it is under it, a command's first line, a memory's name; nil for
-    # the other tools (a plugin's row keeps its preview, the params).
-    # +params+ stays the full key=value line (the TUI, the guardrails).
+    # when it is under it, a command's description (the model's few words),
+    # else its first step and how many more (CommandSteps; its first line
+    # when it has no steps), a memory's name;
+    # nil for the other tools (a plugin's row keeps its preview, the
+    # params). +params+ stays the full key=value line (the TUI, the
+    # guardrails).
     def tool_title(tool_name, call, cwd: nil)
+      if [Tools::Execute::NAME, Tools::TaskCreate::NAME].include?(tool_name)
+        title = command_description(tool_name, call) || steps_title(call[:content])
+        return title if title
+      end
+
       text = case tool_name
              when Tools::Read::NAME, Tools::MemoryRead::NAME then call[:content]
              when Tools::Write::NAME, Tools::Edit::NAME, Tools::MemoryWrite::NAME then call[:path]
@@ -73,6 +94,19 @@ module Samagotchi
     # eats the line.
     LEADING_CD = /\Acd\s+(?:"[^"]*"|'[^']*'|\S+)\s*(?:&&|;)\s*/
 
+    # "<first step> +N" (N the steps after it), cut to fit
+    # TOOL_ACTIVITY_PREVIEW_LIMIT; nil when the command has no steps.
+    def steps_title(command)
+      steps = CommandSteps.parse(command)&.steps
+      return nil unless steps
+
+      first = steps.first.text.gsub(/\s+/, " ")
+      more = steps.size > 1 ? " +#{steps.size - 1}" : ""
+      room = TOOL_ACTIVITY_PREVIEW_LIMIT - more.length
+      first = "#{first[0, room - 1]}…" if first.length > room
+      "#{first}#{more}"
+    end
+
     def command_title(command)
       line = command.to_s.lines.map(&:strip).find { |l| !l.empty? }.to_s
       line.sub(LEADING_CD, "")

data/lib/samagotchi/tool_declarations.rb

@@ -26,6 +26,10 @@ module Samagotchi
               type: "string",
               description: "The shell command to run"
             },
+            description: {
+              type: "string",
+              description: "Optional: what this command does, in a few words (what, not why)"
+            },
             cwd: {
               type: "string",
               description: "Optional working directory to run in (defaults to the project root). Relative paths are resolved against the project root."
@@ -425,6 +429,16 @@ module Samagotchi
 
     module_function
 
+    # +schema+ without execute's description property: what a session
+    # with execute.description off declares (the parameter isn't offered
+    # at all). Any other schema as given.
+    def without_command_description(schema)
+      return schema unless schema[:name] == "execute"
+
+      parameters = schema[:parameters]
+      schema.merge(parameters: parameters.merge(properties: parameters[:properties].except(:description)))
+    end
+
     # Gemma 4 <|tool>declaration:NAME{…}<tool|> blocks for every tool, back
     # to back, as Gemma 4's chat template declares tools.
     # @param schemas [Array<Hash>] a Tools::Registry's schemas

data/lib/samagotchi/tool_view.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "command_steps"
 require_relative "tools/execute"
 require_relative "tools/task_create"
 
@@ -12,9 +13,14 @@ module Samagotchi
   # 80-char cut stay as they are (the guardrails, "ran as:", the TUI).
   #
   # +truncated+: the command was longer than COMMAND_LIMIT and is cut to it;
-  # +chars+ is then its full length.
-  ToolView = Data.define(:command, :cwd, :truncated, :chars) do
-    def to_h = super.compact.reject { |_key, value| value == false }
+  # +chars+ is then its full length. +cd+ and +steps+: the command as
+  # CommandSteps reads it (its leading cd, its steps), both nil when it
+  # can't (the fallback: the UI shows the command itself) or the command
+  # is cut. +description+: what the model said the command does (execute's
+  # optional description), whitespace collapsed, a trailing period gone;
+  # nil when it gave none.
+  ToolView = Data.define(:command, :cwd, :truncated, :chars, :cd, :steps, :description) do
+    def to_h = super.merge(steps: steps&.map(&:to_h)).compact.reject { |_key, value| value == false }
   end
 
   class ToolView
@@ -23,6 +29,11 @@ module Samagotchi
 
     TOOLS = [Tools::Execute::NAME, Tools::TaskCreate::NAME].freeze
 
+    # The longest description a view carries; a row's title shows the
+    # first TITLE_LIMIT characters of it.
+    DESCRIPTION_LIMIT = 300
+    TITLE_LIMIT = 60
+
     # @return [ToolView, nil] nil for a tool without a view and for an
     #   empty command
     def self.for(tool_name, call)
@@ -33,8 +44,33 @@ module Samagotchi
 
       cwd = call[:cwd].to_s.strip
       truncated = command.length > COMMAND_LIMIT
+      parsed = truncated ? nil : CommandSteps.parse(command)
       new(command: truncated ? command[0, COMMAND_LIMIT] : command, cwd: cwd.empty? ? nil : cwd,
-          truncated: truncated, chars: truncated ? command.length : nil)
+          truncated: truncated, chars: truncated ? command.length : nil, cd: parsed&.cd, steps: parsed&.steps,
+          description: description(call))
+    end
+
+    # The call's description as a view shows it, nil for none.
+    def self.description(call)
+      text = call[:description]
+      return nil unless text.is_a?(String)
+
+      text = text.gsub(/\s+/, " ").strip.sub(/(?<!\.)\.\z/, "")
+      return nil if text.empty?
+
+      text.length > DESCRIPTION_LIMIT ? "#{text[0, DESCRIPTION_LIMIT - 1]}…" : text
+    end
+
+    # A row's title from the call's description: cut to TITLE_LIMIT, at a
+    # word when one ends in its second half. nil for none.
+    def self.description_title(call)
+      text = description(call)
+      return text if text.nil? || text.length <= TITLE_LIMIT
+
+      cut = text[0, TITLE_LIMIT - 1]
+      space = cut.rindex(" ")
+      cut = cut[0, space] if space && space >= TITLE_LIMIT / 2
+      "#{cut.sub(/[\s,;:.-]+\z/, "")}…"
     end
   end
 end

data/lib/samagotchi/tools/builtins.rb

@@ -142,11 +142,14 @@ module Samagotchi
         -> { !!peers&.cancelled? }
       end
 
+      # @param command_description [Boolean] false: execute declares no
+      #   description parameter (execute.description off)
       # @return [Registry] a new registry with the built-ins, in
       #   TOOL_SCHEMAS order (an Engine's own, which bundles add to)
-      def registry
+      def registry(command_description: true)
         by_name = CLASSES.to_h { |klass| [klass::NAME, klass] }
         ToolDeclarations::TOOL_SCHEMAS.each_with_object(Registry.new) do |schema, registry|
+          schema = ToolDeclarations.without_command_description(schema) unless command_description
           klass = by_name.fetch(schema[:name])
           handler = HANDLERS.fetch(klass::NAME) { ->(call, _kctx) { klass.call(call[:content]) } }
           registry.register(klass::NAME, schema: schema, handler: handler)

data/lib/samagotchi/tools/execute.rb

@@ -2,6 +2,7 @@
 
 require "open3"
 require_relative "output_guardrails"
+require_relative "shell"
 
 module Samagotchi
   module Tools
@@ -90,7 +91,7 @@ module Samagotchi
         started = monotonic_time
         deadline = started + timeout_sec
 
-        Open3.popen3(env || {}, command, chdir: cwd, pgroup: true) do |stdin, stdout, stderr, wait_thr|
+        Open3.popen3(env || {}, *Shell.argv(command), chdir: cwd, pgroup: true) do |stdin, stdout, stderr, wait_thr|
           stdin.close
           readers = [OutputReader.new(stdout), OutputReader.new(stderr)]
 

data/lib/samagotchi/tools/registry.rb

@@ -3,7 +3,11 @@
 module Samagotchi
   module Tools
     # The tools a session offers the model, in declaration order: the
-    # built-ins (Tools::Builtins), and later the ones bundles add. The
+    # built-ins (Tools::Builtins) as registered, then the ones bundles add,
+    # by bundle and name. That order doesn't depend on which plugin
+    # finished its init first or re-registered a changed tool, so the
+    # tool list (part of the prompt's cached prefix) is the same in every
+    # session with the same tools. The
     # native prompts and the chat path's tools: are rendered from #schemas,
     # and KernelLoop#dispatch runs a call through its entry's handler.
     class Registry
@@ -43,13 +47,16 @@ module Samagotchi
       def key?(name) = @entries.key?(name.to_s)
 
       # @return [Array<String>] in declaration order
-      def names = @entries.keys
+      def names = entries.map(&:name)
 
       # @return [Array<Entry>] in declaration order
-      def entries = @entries.values
+      def entries
+        core, added = @entries.values.partition(&:core?)
+        core + added.sort_by { |entry| [entry.source.to_s, entry.name] }
+      end
 
       # @return [Array<Hash>] the schemas, in declaration order
-      def schemas = @entries.values.map(&:schema)
+      def schemas = entries.map(&:schema)
 
       def freeze
         @entries.freeze

data/lib/samagotchi/tools/shell.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Samagotchi
+  module Tools
+    # The shell a model's (or the user's `!`) command runs in: execute,
+    # task_create and the shell bang. Non-login (a login shell re-sources
+    # profile files, which can rebuild PATH and shadow the inherited toolchain).
+    #
+    # macOS's /bin/sh is bash 3.2, which can't parse an apostrophe in a
+    # heredoc inside "$( )" -- the usual `git commit -m "$(cat <<'EOF' ...`.
+    # There, zsh in sh emulation runs instead (it reads no rc files in that
+    # mode), with the options that keep bash habits working: `{1..3}` brace
+    # expansion, unquoted `( )` in `[[ =~ ]]`, BASH_REMATCH, and echo
+    # expanding `\t` as macOS's sh does. Elsewhere (Linux) /bin/sh as before.
+    module Shell
+      ZSH = "/bin/zsh"
+      ZSH_SH_MODE = [ZSH, "--emulate", "sh", "+o", "ignore_braces", "+o", "sh_glob", "-o", "bash_rematch",
+                     "+o", "bsd_echo"].freeze
+      SH = ["/bin/sh"].freeze
+
+      # @return [Array<String>] the argv that runs +command+
+      def self.argv(command) = [*program, "-c", command]
+
+      # @return [Array<String>] the shell and its options, without -c
+      def self.program(host_os: RbConfig::CONFIG["host_os"], zsh: File.executable?(ZSH))
+        host_os.to_s.include?("darwin") && zsh ? ZSH_SH_MODE : SH
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/task_runtime.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "shellwords"
 require "time"
 require_relative "../atomic_file"
+require_relative "shell"
 
 module Samagotchi
   module Tools
@@ -49,11 +50,10 @@ module Samagotchi
         output_io.sync = true
 
         wrapped_command = wrapped_shell_command(normalized_command, exit_code_path)
-        # Non-login shell (matches Execute): a login shell re-sources profile
-        # files, which can rebuild PATH and shadow the inherited toolchain.
+        # Non-login, the shell Execute uses too (Shell).
         pid = Process.spawn(
           spawn_env,
-          "/bin/sh", "-c", wrapped_command,
+          *Shell.argv(wrapped_command),
           chdir: resolved_cwd,
           out: output_io,
           err: output_io,

data/lib/samagotchi/turn_tally.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "tool_view"
+
 module Samagotchi
   # A running count of one turn's tool calls, for the one-line tally a long,
   # tool-heavy turn shows under its activity row:
@@ -32,10 +34,13 @@ module Samagotchi
 
     # @param key [Object] one call's identity within the turn (the event's
     #   [iteration, call_index])
-    def started(key:, tool:, params: nil)
+    # @param description [String, nil] a command's description, which the
+    #   last call shows in place of its params
+    def started(key:, tool:, params: nil, description: nil)
       call = (@calls[key] ||= { tool: tool.to_s, params: "", status: "running" })
       call[:tool] = tool.to_s unless tool.to_s.empty?
       call[:params] = params.to_s unless params.nil?
+      call[:description] = description if description
       call[:status] = "running"
       call
     end
@@ -43,9 +48,10 @@ module Samagotchi
     # A completion with no start seen still counts as a call (as the web's
     # activity rows do). Only "error" is a failure: a call a guardrail or an
     # approval blocked still counts as a call, not as a failed one.
-    def completed(key:, tool:, status:, params: nil)
-      call = @calls[key] || started(key: key, tool: tool, params: params)
+    def completed(key:, tool:, status:, params: nil, description: nil)
+      call = @calls[key] || started(key: key, tool: tool, params: params, description: description)
       call[:params] = params.to_s if params
+      call[:description] = description if description
       call[:status] = status.to_s == "error" ? "error" : "ok"
       call
     end
@@ -58,7 +64,8 @@ module Samagotchi
         next unless part[:kind].to_s == "tool"
 
         key = [part[:iteration].to_i, part[:call_index].to_i]
-        started(key: key, tool: part[:tool], params: part[:params])
+        view = part[:view].is_a?(Hash) ? part[:view].transform_keys(&:to_sym) : {}
+        started(key: key, tool: part[:tool], params: part[:params], description: ToolView.description_title(view))
         completed(key: key, tool: part[:tool], status: part[:status]) unless part[:status].to_s == "running"
       end
       self
@@ -85,8 +92,12 @@ module Samagotchi
       fields = [head] + top.map { |(tool, n), _| "#{tool} ×#{n}" }
       if last
         call = calls.last
-        params = call[:params].to_s.gsub(/\s+/, " ").strip
-        fields << "last: #{[call[:tool], params].reject(&:empty?).join(" ")}"
+        shown = if call[:description]
+                  "#{call[:tool]}: #{call[:description]}"
+                else
+                  [call[:tool], call[:params].to_s.gsub(/\s+/, " ").strip].reject(&:empty?).join(" ")
+                end
+        fields << "last: #{shown}"
       end
       cut(fields.join(SEPARATOR), width)
     end

data/lib/samagotchi/version.rb

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

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

@@ -17,12 +17,80 @@ export function rowHover(row) {
 // given: execute's may be relative to the project root), the command as
 // written (whitespace kept, its own scroll), a copy button, and a line
 // saying how much a cut command left out. "" for a call without a view.
-export function commandBlockHtml(view) {
+//
+// A view with steps (CommandSteps) shows them in the command's place, its
+// leading cd as one more "in" tag, and a "raw" toggle (a checkbox, CSS
+// only, so a live and a reloaded row behave alike) that swaps the steps
+// for the command as written. The copy button copies the raw command
+// either way. A view without steps (the parser's fallback) is the raw
+// block alone: nothing hides the command.
+//
+// +title+ is the row's: the model's description of the command, when it
+// gave one, cut to fit. The block starts with the whole description when
+// the title is cut, never in place of the command.
+export function commandBlockHtml(view, title = null) {
   const command = view?.command;
   if (!command) return "";
-  const cwd = view.cwd ? `<div class="activity-command-cwd">in <span>${escapeHtml(view.cwd)}</span></div>` : "";
+  const desc = view.description && view.description !== title
+    ? `<div class="activity-command-desc">${escapeHtml(view.description)}</div>`
+    : "";
+  const steps = Array.isArray(view.steps) && view.steps.length ? view.steps : null;
+  const dirs = [view.cwd, steps && view.cd].filter(Boolean);
+  const where = dirs.length
+    ? `in ${dirs.map((d) => `<span>${escapeHtml(d)}</span>`).join(" <span class=\"activity-command-sep\">›</span> ")}`
+    : "";
   const cut = view.truncated
     ? `<div class="activity-command-cut">… (${command.length.toLocaleString("en-US")} of ${Number(view.chars || 0).toLocaleString("en-US")} chars)</div>`
     : "";
-  return `<div class="activity-command code-wrap">${cwd}<pre><code>${escapeHtml(command)}</code></pre>${copyButtonHtml("code")}${cut}</div>`;
+  const raw = `<pre><code>${escapeHtml(command)}</code></pre>`;
+  if (!steps) {
+    const cwd = where ? `<div class="activity-command-cwd">${where}</div>` : "";
+    return `<div class="activity-command code-wrap">${desc}${cwd}${raw}${copyButtonHtml("code")}${cut}</div>`;
+  }
+  const head = `<div class="activity-command-head"><span class="activity-command-cwd">${where}</span>` +
+    `<label class="activity-command-raw" title="Show the command as written"><input type="checkbox">raw</label></div>`;
+  return `<div class="activity-command code-wrap has-steps">${desc}${head}${stepsHtml(steps)}${raw}${copyButtonHtml("code")}${cut}</div>`;
+}
+
+// What an op between two steps reads as: an arrow for "then" (&&, ;, a
+// new line, a pipe), "else" for ||, "&" for one put in the background.
+const OP_GLYPHS = { "&&": "→", ";": "→", "\n": "→", "|": "→", "|&": "→", "||": "else", "&": "&" };
+const OP_NAMES = { "\n": "new line", "&": "after starting the step before in the background" };
+
+function opHtml(op) {
+  if (!op) return `<span class="step-op"></span>`;
+  const glyph = OP_GLYPHS[op] || op;
+  const name = OP_NAMES[op] || op;
+  return `<span class="step-op${op === "||" ? " else" : ""}" title="${escapeHtml(name)}">${escapeHtml(glyph)}</span>`;
+}
+
+// A step's redirections to or from nowhere (2>&1, 2>/dev/null, </dev/null),
+// dimmed: plumbing, not what the step does.
+const PLUMBING = /(^|\s)(\d*>&\d+|&>\/dev\/null|\d*>>?\s*\/dev\/null|<\s*\/dev\/null)(?=\s|$)/g;
+
+export function stepTextHtml(text) {
+  let out = "";
+  let at = 0;
+  for (const m of String(text).matchAll(PLUMBING)) {
+    const start = m.index + m[1].length;
+    out += `${escapeHtml(text.slice(at, start))}<span class="step-plumbing">${escapeHtml(m[2])}</span>`;
+    at = start + m[2].length;
+  }
+  return out + escapeHtml(String(text).slice(at));
+}
+
+// The steps as a list: a label as a small heading above its step, the op
+// that links a step to the one before, its text, its limit and heredoc
+// as chips (beside the text, below it when the row is narrow).
+export function stepsHtml(steps) {
+  const items = steps.map((step) => {
+    const label = step.label ? `<li class="step-label">${escapeHtml(step.label)}</li>` : "";
+    const limit = step.limit ? `<span class="step-chip" title="output limited">${escapeHtml(step.limit)}</span>` : "";
+    const heredoc = step.heredoc
+      ? `<span class="step-chip heredoc" title="a heredoc: its text in the raw command">${escapeHtml(step.heredoc.tag)} · ` +
+        `${Number(step.heredoc.lines)} ${step.heredoc.lines === 1 ? "line" : "lines"}</span>`
+      : "";
+    return `${label}<li class="activity-step">${opHtml(step.op)}<span class="step-body"><code>${stepTextHtml(step.text)}</code>${limit}${heredoc}</span></li>`;
+  });
+  return `<ol class="activity-steps">${items.join("")}</ol>`;
 }

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

@@ -23,11 +23,21 @@ export function noteHtml(note) {
   return `<div class="note-line">${escapeHtml(from)}</div><div class="note-text">${escapeHtml(note?.content ?? "")}</div>`;
 }
 
+// Who a steer names as its sender: a plugin's own label, chi's sender ids
+// in words (the TUI's Formatting#steer_sender agrees;
+// spec/shared/labels_matrix.json). "": no one named.
+const STEER_SENDERS = { parent_agent: "parent agent", chi_send: "chi send", plugin_send: "plugin" };
+export function steerSender(source) {
+  const id = String(source ?? "");
+  return STEER_SENDERS[id] || id;
+}
+
 // A plugin's steer (a nudge put into the running turn): one line that
 // names who nudged the model, its text collapsed under it. +bubble+: on its
 // own between bubbles (no step holds it), not a row of a step.
 export function steerRowHtml({ source, text } = {}, { bubble = false } = {}) {
-  const who = source ? `${source} nudged the model` : "nudged the model";
+  const sender = steerSender(source);
+  const who = sender ? `${sender} nudged the model` : "nudged the model";
   return `<details class="${bubble ? "bubble " : ""}steer-row"><summary>${escapeHtml(who)}</summary>` +
     `<div class="steer-text">${escapeHtml(text ?? "")}</div></details>`;
 }