samagotchi 0.2.0

data/lib/samagotchi/model_overlay.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "tools/memory"
+
+module Samagotchi
+  # Model-specific memory overlays.
+  #
+  # A memory entry `<name>` may have a companion file `<name>.<modelkey>.md` in
+  # the same scope directory. When the entry is read under a matching model, the
+  # overlay body is appended automatically.
+  #
+  # Key invariants:
+  # - The base entry is the contract. An overlay only adds model-specific guidance
+  #   and never contradicts the base protocol.
+  # - One key function is shared by both read and write paths.
+  # - Overlays are resolved only implicitly (via a read of the base); they are
+  #   not first-class memories.
+  class ModelOverlay
+    # Derive the lowercase-dashed key from a bare model name.
+    #
+    # Transform: downcase → replace every non-alphanumeric run with `-` →
+    # squeeze consecutive `-` → trim leading/trailing `-`.
+    #
+    # Examples:
+    #   "qwen3.6-35b-a3b" => "qwen3-6-35b-a3b"
+    #   "gemma4o"         => "gemma4o"
+    #   nil / ""          => nil
+    #
+    # This is THE key function — used by BOTH read and write paths.
+    def self.key_for(model_name)
+      return nil if model_name.nil? || model_name.to_s.strip.empty?
+
+      key = model_name.to_s
+        .downcase
+        .gsub(/[^a-z0-9]+/, "-")
+        .gsub(/-+/, "-")
+        .sub(/\A-/, "")
+        .sub(/-\z/, "")
+      key.empty? ? nil : key
+    end
+
+    # Return the expected file path for an overlay in the given scope.
+    # Respects MemoryBundle overrides (delegates to Tools::MemoryRead.memories_dir).
+    def self.overlay_path_for(name, key, scope)
+      return nil unless key && !key.to_s.strip.empty?
+      File.join(Tools::MemoryRead.memories_dir(scope), "#{name}.#{key.to_s.strip}.md")
+    end
+
+    # Regex matching overlay file names: /<something>.<lowercase-dashed-key>.md\z
+    # Useful for tooling, tests, and future index suppression.
+    OVERLAY_SUFFIX_PATTERN = /\.([a-z0-9\-]+)\.md\z/
+  end
+end

data/lib/samagotchi/model_profile.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require_relative "log"
+module Samagotchi
+  # Encapsulates all model-specific token formats and parsing behavior.
+  # Each profile maps to a model family; ModelProfile.resolve picks one
+  # (config, the server's chat template, the name, then qwen36).
+  #
+  # Current profiles:
+  #   qwen36  — Qwen 3.6 chat template with function calling (the default)
+  #   gemma4  — Gemma 4 format
+  class ModelProfile
+    MODEL_ENV = "SAMAGOTCHI_DEFAULT_MODEL"
+    # No model anywhere (--model, default.model in config.yml, the env): a
+    # first run before any config. An ArgumentError, as before.
+    MissingModel = Class.new(ArgumentError)
+
+    attr_reader :name, :turn_start, :turn_end,
+                :tool_call_open, :tool_call_close,
+                :tool_response_open, :tool_response_close,
+                :string_delim,
+                :thought_open, :thought_close,
+                :system_prefix, :user_prefix, :assistant_prefix,
+                :model_prefix,
+                :stop_sequences, :tool_decl_format,
+                :image_template
+
+    def initialize(config)
+      @name = config[:name]
+      @turn_start = config[:turn_start]
+      @turn_end = config[:turn_end]
+      @tool_call_open = config[:tool_call_open]
+      @tool_call_close = config[:tool_call_close]
+      @tool_response_open = config[:tool_response_open]
+      @tool_response_close = config[:tool_response_close]
+      @string_delim = config[:string_delim]
+      @thought_open = config[:thought_open]
+      @thought_close = config[:thought_close]
+      @system_prefix = config[:system_prefix]
+      @user_prefix = config[:user_prefix]
+      @assistant_prefix = config[:assistant_prefix]
+      @model_prefix = config[:model_prefix]
+      @stop_sequences = config[:stop_sequences]
+      @tool_decl_format = config[:tool_decl_format]
+      # How the chat template wraps an image's media marker ("%{marker}"),
+      # or nil when chi doesn't know it yet (native images are refused).
+      @image_template = config[:image_template]
+    end
+
+    # The token the image template opens with, e.g. "<|vision_start|>": the
+    # server's chat template must use it too (VisionSupport).
+    def image_open_token
+      image_template&.split("%{marker}")&.first.to_s
+    end
+
+    def self.gemma4
+      new(
+        name: "gemma4",
+        turn_start: "<|turn>",
+        turn_end: "<end_of_turn>",
+        tool_call_open: "<|tool_call>",
+        tool_call_close: "<tool_call|>",
+        tool_response_open: "<|tool_response>",
+        tool_response_close: "<tool_response|>",
+        string_delim: '<|"|>',
+        thought_open: "<|think|>",
+        thought_close: nil,
+        system_prefix: "",
+        user_prefix: "",
+        assistant_prefix: "",
+        model_prefix: "",
+        stop_sequences: ["<end_of_turn>", "<|tool_response>"],
+        tool_decl_format: :gemma4
+      )
+    end
+
+    def self.qwen36
+      new(
+        name: "qwen36",
+        turn_start: "",
+        turn_end: "",
+        tool_call_open: "<tool_call>",
+        tool_call_close: "</tool_call>",
+        tool_response_open: "<tool_response>",
+        tool_response_close: "</tool_response>",
+        string_delim: nil,
+        thought_open: "<think>",
+        thought_close: "</think>",
+        system_prefix: "<|im_start|>system\n",
+        user_prefix: "<|im_start|>user\n",
+        assistant_prefix: "<|im_start|>assistant\n",
+        model_prefix: "<|im_start|>assistant\n",
+        stop_sequences: ["<|im_end|>"],
+        tool_decl_format: :qwen36,
+        image_template: "<|vision_start|>%{marker}<|vision_end|>"
+      )
+    end
+
+    def self.default
+      gemma4
+    end
+
+    def self.normalize(value)
+      return value if value.is_a?(self)
+
+      case value.to_s.strip.downcase
+      when "qwen", "qwen3", "qwen36", "qwen3.6"
+        qwen36
+      when "gemma", "gemma4", "gemma4o"
+        gemma4
+      else
+        gemma4
+      end
+    end
+
+    def self.required_model_name(model_name = nil, env: ENV)
+      value = model_name.to_s.strip
+      if value.empty?
+        begin
+          require_relative "config"
+          cfg = Samagotchi::Config.get("default.model") rescue nil
+          value = cfg.to_s.strip unless cfg.nil? || cfg.to_s.strip.empty?
+        rescue StandardError
+          nil
+        end
+      end
+      value = env[MODEL_ENV].to_s.strip if value.empty?
+      raise MissingModel, missing_model_message if value.empty?
+
+      value
+    end
+
+    # One line for the user: where to set the model.
+    def self.missing_model_message
+      path = begin
+        require_relative "config"
+        Samagotchi::ConfigFile.global_path
+      rescue StandardError, LoadError
+        "~/.config/samagotchi/config.yml"
+      end
+      "no model configured: set default.model in #{path} to the model id your server serves " \
+        "(or #{MODEL_ENV}, or pass --model ID); see docs/configuration.md"
+    end
+
+    def self.from_model_name(model_name)
+      named(inferred_profile_name(model_name))
+    end
+
+    # qwen → qwen36, gemma → gemma4, anything else → DEFAULT_NAME: many
+    # models with other names are Qwen-based, and under the gemma4 profile a
+    # ChatML model never hits a stop sequence.
+    def self.inferred_profile_name(model_name)
+      normalized = model_name.to_s.strip.downcase
+      return "qwen36" if normalized.include?("qwen")
+      return "gemma4" if normalized.include?("gemma")
+
+      DEFAULT_NAME
+    end
+
+    def self.from_env
+      from_model_name(required_model_name(nil, env: ENV))
+    end
+
+    # ── Resolution: which profile a model gets ───────────────────────────
+
+    NAMES = %w[qwen36 gemma4].freeze
+
+    # The last layer, when nothing else says.
+    DEFAULT_NAME = "qwen36"
+
+    # What the server's chat template must contain for each profile. The
+    # template tells the families apart where eos_token doesn't (Gemma 4's is
+    # <eos> or <turn|>, depending on who packed it). llama.cpp itself detects
+    # Gemma 4 by '<|tool_call>call:'.
+    FINGERPRINTS = {
+      "qwen36" => ["<|im_start|>", "<function="],
+      "gemma4" => ["<|turn>", "<|tool_call>"]
+    }.freeze
+
+    # A resolved profile and where it came from. source: :cli, :env,
+    # :config, :server, :name or :default; detail: the config key, the
+    # template evidence or the matched name. retry: the server probe failed
+    # (unreachable, or loading and answering 503), so the caller should
+    # resolve again before its next turn.
+    Resolution = Data.define(:profile, :source, :detail, :retry) do
+      def retry? = self.retry
+
+      # How /stats, /model and chi self name the source.
+      def label
+        case source
+        when :config then "config (#{detail})"
+        when :server then "server (chat_template)"
+        else source.to_s
+        end
+      end
+    end
+
+    # The profile called +value+, or nil (unlike .normalize, which always
+    # gives one).
+    def self.named(value)
+      name = value.to_s.strip.downcase
+      NAMES.include?(name) ? public_send(name) : nil
+    end
+
+    # [profile name, evidence] from a llama.cpp /props body, or nil when its
+    # chat template says neither family. A ChatML template without Qwen's
+    # <function= calls (older Qwen3, Hermes, ...) still gets qwen36: its
+    # <|im_end|> stops generation, where gemma4's stop sequences never occur.
+    def self.fingerprint(props)
+      template = props.is_a?(Hash) ? props["chat_template"].to_s : ""
+      FINGERPRINTS.each do |name, markers|
+        return [name, markers.join(" + ")] if markers.all? { |marker| template.include?(marker) }
+      end
+      return ["qwen36", "ChatML"] if template.include?("<|im_start|>")
+
+      nil
+    end
+
+    # Which profile a model gets, first match wins:
+    #   1. override: --profile / SAMAGOTCHI_MODEL_PROFILE ([value, origin];
+    #      a nil value is not set, whatever its origin)
+    #   2. models: in the config file, under any of +names+
+    #   3. hosts.<name>.profile of +entry+
+    #   4. the server's chat template (native llama.cpp hosts only)
+    #   5. the name: qwen → qwen36, gemma → gemma4
+    #   6. DEFAULT_NAME
+    # An unknown configured value warns and is skipped.
+    #
+    # @param names [Array<String>] the model as typed, alias-resolved, bare
+    # @param entry [HostRegistry::HostEntry, nil] the model's host
+    # @param client [#server_props, nil] the host's client (nil: no probe)
+    # @param bare_model [String, nil] the name the probe asks the server about
+    # @return [Resolution]
+    def self.resolve(names:, entry:, client:, bare_model:, override: nil, models: nil)
+      require_relative "config"
+      override ||= Samagotchi::Config.get_with_origin("model.profile")
+      models ||= Samagotchi::ConfigFile.model_settings
+      names = Array(names).map { |n| n.to_s.strip }.reject(&:empty?).uniq
+
+      value, origin = override
+      if (profile = named(value))
+        return Resolution.new(profile: profile, source: origin == :env ? :env : :cli, detail: nil, retry: false)
+      end
+
+      names.map(&:downcase).uniq.each do |key|
+        setting = models[key]
+        next unless setting && setting[:profile]
+
+        profile = configured(setting[:profile], "models: #{key}")
+        return Resolution.new(profile: profile, source: :config, detail: "models: #{key}", retry: false) if profile
+      end
+
+      if entry&.profile && (profile = configured(entry.profile, "hosts.#{entry.name}"))
+        return Resolution.new(profile: profile, source: :config, detail: "hosts.#{entry.name}", retry: false)
+      end
+
+      retry_later = false
+      if probe?(entry, client)
+        props = client.server_props(model: bare_model)
+        if props && !props.answered?
+          retry_later = true
+        elsif props && (found = fingerprint(props.body))
+          return Resolution.new(profile: named(found[0]), source: :server, detail: found[1], retry: false)
+        end
+      end
+
+      names.each do |name|
+        lowered = name.downcase
+        family = if lowered.include?("qwen") then "qwen36"
+                 elsif lowered.include?("gemma") then "gemma4"
+                 end
+        return Resolution.new(profile: named(family), source: :name, detail: name, retry: retry_later) if family
+      end
+
+      Resolution.new(profile: named(DEFAULT_NAME), source: :default, detail: nil, retry: retry_later)
+    end
+
+    def self.configured(value, where)
+      profile = named(value)
+      Log.warn(:config, "unknown_profile", echo: "Warning: unknown profile #{value.to_s.inspect} in #{where} (allowed: #{NAMES.join(', ')}) — ignored", profile: value.to_s, where: where) unless profile
+      profile
+    end
+    private_class_method :configured
+
+    # Only a native llama.cpp host has /props with a chat template; a chat
+    # host (api: openai) barely uses a profile, and mlx/oMLX expose none.
+    def self.probe?(entry, client)
+      return false if client.nil? || !client.respond_to?(:server_props)
+      return false if entry&.chat?
+
+      !client.respond_to?(:transport) || client.transport.name == :llama_cpp
+    end
+    private_class_method :probe?
+
+    # ── Thought channel support ──────────────────────────────────────────
+
+    def thought_channel_open
+      nil
+    end
+
+    def uses_channel_thoughts?
+      false
+    end
+
+    def uses_role_prefixes?
+      !system_prefix.empty? && !user_prefix.empty?
+    end
+  end
+end

data/lib/samagotchi/muted_memories.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "tools/memory"
+
+module Samagotchi
+  # Memories hidden from one session (`--mute NAME`): name normalization and
+  # the index-text filter, shared by the Engine (the prompt's index, the
+  # identity auto-load, the preload list) and the KernelLoop (a memory_read
+  # guard). Nothing on disk changes: a muted memory keeps its file and its
+  # index line.
+  module MutedMemories
+    # A managed index line (IndexUpdater.managed_line), plus the legacy
+    # `- **name**: desc` and `- **name.md** ·` shapes still found in indexes.
+    INDEX_LINE = /\A- \*\*(.+?)\*\*[ \t]*(?:[·•].*|:.*)?\z/
+
+    # `project/gh-helper`, `gh-helper.md`, ` gh-helper ` → `gh-helper`.
+    # nil for a blank name.
+    def self.normalize(raw)
+      value = raw.to_s.strip
+      return nil if value.empty?
+
+      if value.include?("/")
+        scope, rest = value.split("/", 2)
+        value = rest if Tools::VALID_SCOPES.include?(scope)
+      end
+      base = File.basename(value, ".md").strip
+      base.empty? ? nil : base
+    end
+
+    # Names as given (comma lists allowed) → normalized, deduped.
+    def self.normalize_list(names)
+      Array(names).flat_map { |raw| raw.to_s.split(",") }.map { |n| normalize(n) }.compact.uniq
+    end
+
+    def self.muted?(name, muted)
+      return false if muted.nil? || muted.empty?
+
+      key = normalize(name)
+      !key.nil? && muted.include?(key)
+    end
+
+    # The index text without the lines that name a muted memory: a managed
+    # line (`- **name** · …`) or a bare name (the "no index yet" fallback).
+    # Every other byte stays.
+    def self.filter_index(text, muted)
+      return text if muted.nil? || muted.empty? || text.nil?
+
+      text.each_line.reject { |line| muted_index_line?(line, muted) }.join
+    end
+
+    def self.muted_index_line?(line, muted)
+      muted?(index_line_name(line), muted)
+    end
+
+    # The memory an index line names, normalized: a managed line's
+    # `**name**`, else the bare line (the "no index yet" list). nil for a
+    # line that names none (a heading, prose with spaces).
+    def self.index_line_name(line)
+      stripped = line.chomp
+      name = stripped.match(INDEX_LINE)&.[](1) || stripped
+      return nil if name.include?(" ")
+
+      normalize(name)
+    end
+  end
+end

data/lib/samagotchi/note_command.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "session_manager"
+
+module Samagotchi
+  # `chi note`: push text into sessions as a context note (background the
+  # model sees on its next turn), never as a prompt; nothing wakes. For a
+  # script, e.g. an Automator action:
+  #   pbpaste | chi note --source slack $(chi sessions list --live --scope=all --format tsv | cut -f1)
+  class NoteCommand
+    USAGE = <<~TEXT
+      Usage: chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all
+        Adds TEXT (or stdin) to each session as a context note: background
+        the model sees on its next turn, not a prompt. It starts no turn.
+        --source NAME  where it came from, shown to the model (default: cli)
+        -m TEXT        the note; without it, stdin is read
+        --all          every session a worker runs now, in every project
+        Find ids with: chi sessions list --live [--scope=all] [--format tsv]
+    TEXT
+
+    # @param argv [Array<String>] the arguments after "note"
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil)
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @state_dir = state_dir || Session.default_state_dir
+    end
+
+    # @return [Integer] exit status: 0 all queued, 1 any refused or failed,
+    #   2 usage
+    def run
+      options = parse or return 2
+      return 0 if options[:help]
+
+      text = utf8(options[:text] || read_stdin)
+      unless text
+        usage_error("no note text: pass -m TEXT or pipe it in")
+        return 2
+      end
+      begin
+        text = SessionManager.checked_text(text)
+      rescue SessionManager::NoteRejected => e
+        @stderr.puts("chi note: #{e.message}")
+        return 1
+      end
+
+      return deliver_to_live(text, options[:source]) if options[:all]
+
+      # One id at a time, so each line follows the order of the ids given.
+      seen = {}
+      results = options[:ids].uniq.map do |given|
+        id = resolve(given)
+        next false unless id
+        next true if seen[id]
+
+        seen[id] = true
+        deliver(id, text, options[:source])
+      end
+      results.all? ? 0 : 1
+    end
+
+    private
+
+    def parse
+      options = { source: "cli", ids: [] }
+      until @argv.empty?
+        arg = @argv.shift
+        case arg
+        when "-h", "--help", "help"
+          @stdout.puts(USAGE)
+          return { help: true }
+        when "--all" then options[:all] = true
+        when "--source", "-m", "--message"
+          value = @argv.shift or return usage_error("#{arg} needs a value")
+          options[arg == "--source" ? :source : :text] = value
+        when /\A--source=(.*)\z/m then options[:source] = Regexp.last_match(1)
+        when /\A--message=(.*)\z/m then options[:text] = Regexp.last_match(1)
+        when /\A-/ then return usage_error("unknown option #{arg}")
+        else options[:ids] << arg
+        end
+      end
+      return usage_error("give session ids or --all") if options[:ids].empty? && !options[:all]
+      return usage_error("--all takes no ids") if options[:all] && options[:ids].any?
+
+      options
+    end
+
+    # Only a pipe or a file is read, as chi send does. A terminal means
+    # nobody piped a note in, and a socket a launcher or an agent's shell
+    # passes down may never close: waiting on either would hang a script.
+    def read_stdin
+      return nil if @stdin.respond_to?(:tty?) && @stdin.tty?
+      if @stdin.respond_to?(:stat)
+        stat = @stdin.stat
+        return nil unless stat.pipe? || stat.file?
+      end
+
+      @stdin.read
+    end
+
+    # --all: every live session. @return [Integer] exit status
+    def deliver_to_live(text, source)
+      ids = SessionManager.session_summaries(live: true, include_tests: false, state_dir: @state_dir).map { |s| s[:id] }
+      if ids.empty?
+        error_line("chi note: no live sessions (chi sessions list --live --scope=all)")
+        return 1
+      end
+
+      ids.map { |id| deliver(id, text, source) }.all? ? 0 : 1
+    end
+
+    def resolve(given)
+      id = Session.resolve_id(given, state_dir: @state_dir)
+      Session.load(id, state_dir: @state_dir)
+      id
+    rescue ArgumentError => e
+      message = e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"
+      error_line("chi note: #{message}")
+      nil
+    end
+
+    # @return [Boolean] whether the note was queued
+    def deliver(id, text, source)
+      short = id[0, 8]
+      owner = SessionManager.session_owner(id, state_dir: @state_dir)
+      if owner && owner["kind"] == "tui"
+        @stdout.puts("#{short}  refused: it is open in a chi REPL; notes need attached mode")
+        return false
+      end
+
+      path = SessionManager.write_note(id, text: text, source: source, state_dir: @state_dir)
+      if owner
+        @stdout.puts("#{short}  queued: its worker adds it within a few seconds")
+      else
+        queued = SessionManager.find_new_note_files(File.dirname(File.dirname(path))).size
+        @stdout.puts("#{short}  waits for the session's next start (#{queued} #{queued == 1 ? "note" : "notes"} queued)")
+      end
+      true
+    end
+
+    # The note as UTF-8 whatever the locale says: with no LANG/LC_* (an app
+    # started from Finder, launchd) stdin reads as US-ASCII and ARGV as
+    # binary. Invalid bytes become U+FFFD rather than an error.
+    def utf8(text)
+      text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
+    end
+
+    # stderr isn't buffered, stdout is when it's a pipe: flush the lines
+    # already printed, so the output keeps the order of the ids given.
+    def error_line(text)
+      @stdout.flush
+      @stderr.puts(text)
+    end
+
+    def usage_error(message)
+      error_line("chi note: #{message}")
+      @stderr.puts(USAGE)
+      nil
+    end
+  end
+end

data/lib/samagotchi/output_formatter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+module Samagotchi
+  # OutputFormatter strips model wire-format tokens from raw engine output at
+  # render time, so downstream renderers (web UI, terminal UI) never show the
+  # model's internal control/literal vocabulary.
+  #
+  # Two token families survive KernelLoop#run's strip_thought_blocks():
+  #   * Gemma control tokens: <|turn>, <|tool_call>...<tool_call|>,
+  #     <|tool_response>...<tool_response|>, <|think|>, <|channel>thought...,
+  #     <channel|>, <|tool>declaration...<tool|> blocks, <|"|> delimiter.
+  #   * Qwen prompt-literal blocks: [[SAMAGOTCHI_LITERAL_*]]
+  #     (<tool_call>, </think>,
+  #     …) which strip_thought_blocks does NOT remove.
+  #
+  # IMPORTANT: control-token matching is ENUMERATED by name, never a broad
+  # <[a-z_]{1,40}> wildcard. A wildcard eats arbitrary <word> content in
+  # tool/file output (e.g. a tool result containing "<div>" or "<resp>" would be
+  # silently mangled). If a new control token is added elsewhere, add its name to
+  # CONTROL_NAMES (and any new bare-literal form) here before it can appear in
+  # rendered output.
+  module OutputFormatter
+    # The complete vocabulary of known control-token names. Matched inside their
+    # wrapper forms; bare <name> content (no pipe) is deliberately preserved.
+    CONTROL_NAMES = %w[
+      turn
+      end_of_turn
+      tool_call
+      tool_response
+      tool
+      think
+      channel
+    ].freeze
+
+    # Tokens are stripped individually by name (INDIVIDUAL_RE), which preserves the
+    # tool-call / declaration *body* content while removing only the markers. The
+    # body (e.g. `call:read{path:'x'}`) is real, readable output and must remain.
+
+    # Individual control tokens matched inside their wrapper forms. Each
+    # alternative requires at least one pipe (leading or trailing) so a bare
+    # <word> in the surrounding content is NOT stripped:
+    #   <|name> / <name|> / <|name|>
+    INDIVIDUAL_RE = Regexp.new(
+      '<\\|(?:' + CONTROL_NAMES.join('|') + ')\\|?>' \
+      '|<(?:' + CONTROL_NAMES.join('|') + ')\\|>'
+    )
+    INDIVIDUAL_RE.freeze
+
+    # Angle-bracketed literal tokens stripped wholesale (including the thought
+    # channel's trailing word). Applied before INDIVIDUAL_RE so multi-part tokens
+    # are removed as a unit.
+    # Angle-bracketed literal tokens stripped wholesale (including the thought
+    # channel's trailing word). Applied before INDIVIDUAL_RE so multi-part tokens
+    # are removed as a unit. Pipes are escaped; angle brackets are literal.
+    LITERALS_RE = /<\|"\|>|<\|\w*channel>thought|<end_of_turn>/.freeze
+
+    # Qwen prompt-literal placeholders, e.g. </think>.
+    PROMPT_LITERALS = /\[\[SAMAGOTCHI_LITERAL_[A-Z_]+\]\]/.freeze
+
+    # Qwen3.6 thinking blocks: <think>...</think> (including empty)
+    QWEN_THINK_RE = /<think>.*?<\/think>/m.freeze
+    # Qwen tool_call XML blocks that survive when a tool call is rendered as text
+    # e.g. <tool_call>\n<function=list_reminders>\n</function>\n</tool_call>
+    QWEN_TOOL_CALL_RE = /<tool_call>.*?<\/tool_call>/m.freeze
+    module_function
+
+    # Remove both control-token and prompt-literal token families from +text+.
+    # Known literals are stripped first (as whole units), then remaining tokens are
+    # stripped by name inside their wrappers (bodies preserved). Whitespace runs
+    # are collapsed and leading/trailing whitespace trimmed so removing a mid-sentence
+    # tag leaves no stray double-space or blank line. Internal newlines are preserved
+    # so a multi-line response stays readable. Blank / token-only input returns "".
+    def strip(text)
+      cleaned =
+        remove_tokens(text)
+        .gsub(/[ \t]+/, " ")
+        .gsub(/ *\n */, "\n")
+        .strip
+      cleaned.empty? ? '' : cleaned
+    end
+
+    # The same tokens as #strip, but the text keeps its layout (indentation,
+    # runs of spaces); only the blank lines removed blocks leave collapse.
+    # For showing a whole saved message (the attached TUI's join, the web history).
+    def strip_markup(text)
+      remove_tokens(text).gsub(/\n[ \t]*\n(?:[ \t]*\n)+/, "\n\n").strip
+    end
+
+    def remove_tokens(text)
+      text.to_s
+          .gsub(QWEN_THINK_RE, '')
+          .gsub(QWEN_TOOL_CALL_RE, '')
+          .gsub(LITERALS_RE, '')
+          .gsub(INDIVIDUAL_RE, '')
+          .gsub(PROMPT_LITERALS, '')
+          # orphaned closing tags that may remain after block removal
+          .gsub(/<\/?think>/, '')
+          .gsub(/<\/?tool_call>/, '')
+    end
+  end
+end