samagotchi 0.2.0

data/lib/samagotchi/thinking_ticker.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Live thinking as one sentence at a time, for the terminal: the Ruby side
+  # of the web's sentences.js + thinking_ticker.js, with the same rules.
+  #
+  # Sentence boundary: [.!?…] optionally followed by closing quotes or
+  # brackets, then whitespace; a newline is also a boundary, and so is the end
+  # of the text (the ticker corrects itself on the next chunk). A bare list
+  # number ("1.", "118.") at the start of a line is a marker, not a sentence.
+  # Whitespace is collapsed. A trailing fragment longer than MAX_LEN (a
+  # code-like run with no punctuation) counts as the current sentence.
+  #
+  # The ticker changes its line no sooner than DWELL seconds after the last
+  # change, so a fast stream doesn't flicker: in between, the newest sentence
+  # waits and #tick shows it when the dwell is over.
+  class ThinkingTicker
+    MAX_LEN = 160
+    DWELL = 1.5
+    BOUNDARY = /([.!?…][)"'\]]*)([[:space:]]|\z)|\n/
+    LIST_MARKER = /\A\d{1,4}\.\z/
+
+    # @return [Array<String>] every complete sentence of +text+ (the end
+    #   counts as a boundary), collapsed, blanks skipped
+    def self.sentences(text)
+      raw = text.to_s
+      found = []
+      start = 0
+      raw.to_enum(:scan, BOUNDARY).each do
+        m = Regexp.last_match
+        candidate = raw[start...(m.begin(0) + m[1].to_s.length)]
+        # A list number is no sentence: keep reading from the same start.
+        next if LIST_MARKER.match?(candidate.strip)
+
+        collapsed = collapse(candidate)
+        found << collapsed unless collapsed.empty?
+        start = m.end(0)
+      end
+      found
+    end
+
+    # The newest complete sentence of +text+, else the trailing fragment when
+    # longer than +max_len+, else "".
+    def self.current_sentence(text, max_len: MAX_LEN)
+      last = sentences(text).last
+      return last if last
+
+      fragment = collapse(text)
+      fragment.length > max_len ? fragment : ""
+    end
+
+    def self.collapse(text)
+      text.to_s.gsub(/[[:space:]]+/, " ").strip
+    end
+
+    attr_reader :line
+
+    # @param clock [#call] seconds, monotonic
+    def initialize(clock:, dwell: DWELL)
+      @clock = clock
+      @dwell = dwell
+      reset
+    end
+
+    # Forget the line (a new generation).
+    def reset
+      @line = ""
+      @pending = nil
+      @changed_at = nil
+    end
+
+    # Show the newest sentence of +text+ now, or keep it pending for the
+    # dwell. @return [Boolean] whether the line changed
+    def feed(text)
+      candidate = self.class.current_sentence(text)
+      return false if candidate.empty?
+
+      if candidate == @line
+        @pending = nil
+        false
+      elsif @line.empty? || due?
+        show(candidate)
+      else
+        @pending = candidate
+        false
+      end
+    end
+
+    # Show a pending sentence once the dwell is over.
+    # @return [Boolean] whether the line changed
+    def tick
+      return false unless @pending && due?
+
+      show(@pending)
+    end
+
+    private
+
+    def due?
+      @changed_at.nil? || @clock.call - @changed_at >= @dwell
+    end
+
+    def show(candidate)
+      @line = candidate
+      @pending = nil
+      @changed_at = @clock.call
+      true
+    end
+  end
+end

data/lib/samagotchi/thought_stream_splitter.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "model_profile"
+
+module Samagotchi
+  # Incremental, profile-aware splitter for a raw model stream.
+  #
+  # It feeds raw streamed chunks (the `:generation_chunk` `content`, which is
+  # never mutated) and routes each byte into one of two additive lanes:
+  #   * :thinking — content inside a thinking block
+  #   * :text     — visible prose (everything outside thinking/tool_call blocks)
+  #
+  # tool_call block bodies are dropped: the web activity panel renders those from
+  # the `:tool_call_started` / `:tool_call_completed` events, so duplicating them
+  # in the text bubble would be noise.
+  #
+  # The splitter is stateful across chunks: it carries partial open/close marker
+  # fragments at the end of each chunk so a marker split across a stream boundary
+  # is still recognized. `ThoughtStreamSplitter.for_profile` derives the block
+  # markers from the active ModelProfile, so the same splitter works for the
+  # Qwen literal-marker family and (tool_call only) the Gemma control-token family.
+  #
+  # For a profile whose `thought_close` is nil (Gemma 4), thinking blocks have no
+  # explicit close marker and are NOT split out — they remain in `:text` and the
+  # renderer's existing strip still hides them from the bubble. Qwen 3.6 (the
+  # default runtime profile) has explicit open/close markers for both families,
+  # so thinking is split cleanly.
+  class ThoughtStreamSplitter
+    # @return [Array<Hash>] each entry { open: String, close: String, lane: :thinking|:drop }
+    def self.for_profile(profile)
+      blocks = []
+      # Only register a thinking block when the profile has an explicit close
+      # marker (Qwen). A nil close (Gemma) means we can't bound the block, so we
+      # leave thinking in :text and let the renderer's strip handle it.
+      blocks << { open: profile.thought_open, close: profile.thought_close, lane: :thinking } if profile.thought_close
+      blocks << { open: profile.tool_call_open, close: profile.tool_call_close, lane: :drop }
+      new(blocks)
+    end
+
+    # @param blocks [Array<Hash>] as produced by #for_profile
+    def initialize(blocks)
+      @blocks = blocks
+      @carry = +""
+      @state = :normal
+      @active = nil
+    end
+
+    # Feed one raw chunk. Returns the newly-routed deltas for this chunk only.
+    # @return [Hash{ text: String, thinking: String }]
+    def feed(chunk)
+      @carry << chunk.to_s
+      text = +""
+      thinking = +""
+      loop do
+        if @state == :normal
+          hit = earliest_open
+          if hit.nil?
+            flush_normal(text)
+            break
+          end
+          # Everything before the open marker is visible prose.
+          text << @carry[0...hit[:pos]]
+          @carry = @carry[hit[:pos]..]
+          @active = hit[:block]
+          @state = :in_block
+          # Drop the open marker itself; its body follows.
+          @carry = @carry[@active[:open].length..].to_s
+        else
+          close_pos = @carry.index(@active[:close])
+          if close_pos.nil?
+            flush_in_block(thinking)
+            break
+          end
+          body = @carry[0...close_pos]
+          route_body(body, thinking)
+          @carry = @carry[close_pos + @active[:close].length..].to_s
+          @active = nil
+          @state = :normal
+        end
+      end
+      { text: text, thinking: thinking }
+    end
+
+    # Flush any residual state at end of stream (e.g. an unterminated thinking
+    # block: its content is still thinking; a partial trailing marker is
+    # discarded since it can no longer complete).
+    # @return [Hash{ text: String, thinking: String }]
+    def finalize
+      text = +""
+      thinking = +""
+      if @state == :in_block
+        route_body(@carry, thinking)
+      else
+        text << @carry
+      end
+      @carry = +""
+      @active = nil
+      @state = :normal
+      { text: text, thinking: thinking }
+    end
+
+    private
+
+    # Normal state: the earliest complete open marker among @blocks, or nil.
+    def earliest_open
+      best = nil
+      @blocks.each do |block|
+        pos = @carry.index(block[:open])
+        next if pos.nil?
+        best = { pos: pos, block: block } if best.nil? || pos < best[:pos]
+      end
+      best
+    end
+
+    # Normal state: emit everything except a trailing fragment that could be the
+    # start of an open marker (retained for the next chunk to complete it).
+    def flush_normal(text)
+      partial = @blocks.map { |block| longest_suffix_prefix_of(@carry, block[:open]) }.max.to_i
+      text << @carry[0...(@carry.length - partial)]
+      @carry = @carry[@carry.length - partial..].to_s
+    end
+
+    # In-block state: emit the body seen so far to the active lane, retaining a
+    # trailing fragment that could be the start of the close marker.
+    def flush_in_block(thinking)
+      close = @active[:close]
+      partial = longest_suffix_prefix_of(@carry, close)
+      route_body(@carry[0...(@carry.length - partial)], thinking)
+      @carry = @carry[@carry.length - partial..].to_s
+    end
+
+    # Route a body fragment to the active block's lane (:thinking or :drop).
+    def route_body(body, thinking)
+      return if body.nil? || body.empty?
+      thinking << body if @active && @active[:lane] == :thinking
+    end
+
+    # Length of the longest suffix of +str+ that is a prefix of +marker+.
+    # Used to hold back a fragment that may complete into a marker next chunk.
+    def longest_suffix_prefix_of(str, marker)
+      mlen = marker.length
+      return 0 if mlen.zero? || str.empty?
+      [str.length, mlen].min.downto(1) do |n|
+        return n if str[-n..] == marker[0, n]
+      end
+      0
+    end
+  end
+end

data/lib/samagotchi/token_usage.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # TokenUsage extracts real server-reported token counts from a model API
+  # stream payload, transport-agnostically.
+  #
+  # llama.cpp's /completion stream emits per-chunk `timings.prompt_n` /
+  # `timings.predicted_n` (cumulative) and a final top-level
+  # `tokens_evaluated` / `tokens_predicted`. mlx_lm.server (OpenAI-compatible)
+  # emits a `usage` object with `prompt_tokens` / `completion_tokens`.
+  #
+  # Returns nil when no server token data is 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
+    CHARS_PER_TOKEN = 4.0
+
+    class << self
+      # @param payload [Hash, nil] the raw streamed chunk payload
+      # @return [Hash, nil] { prompt_tokens:, completion_tokens:, source: :server }
+      def from_payload(payload)
+        payload_hash = payload.is_a?(Hash) ? payload : {}
+        usage = payload_hash["usage"] || payload_hash[:usage]
+        usage = {} unless usage.is_a?(Hash)
+
+        prompt_tokens = first_positive(
+          usage["prompt_tokens"],
+          usage[:prompt_tokens],
+          payload_hash["prompt_tokens"],
+          payload_hash[:prompt_tokens],
+          payload_hash["prompt_n"],
+          payload_hash[:prompt_n],
+          payload_hash["tokens_evaluated"],
+          payload_hash[:tokens_evaluated],
+          payload_hash.dig("timings", "prompt_n"),
+          payload_hash.dig(:timings, :prompt_n)
+        )
+
+        completion_tokens = first_positive(
+          usage["completion_tokens"],
+          usage[:completion_tokens],
+          payload_hash["completion_tokens"],
+          payload_hash[:completion_tokens],
+          payload_hash["predicted_n"],
+          payload_hash[:predicted_n],
+          payload_hash["tokens_predicted"],
+          payload_hash[:tokens_predicted],
+          payload_hash.dig("timings", "predicted_n"),
+          payload_hash.dig(:timings, :predicted_n)
+        )
+
+        return nil unless prompt_tokens || completion_tokens
+
+        {
+          prompt_tokens: prompt_tokens,
+          completion_tokens: completion_tokens,
+          source: :server
+        }
+      end
+
+      # Estimate token count from raw text length using the chars/4 heuristic.
+      # @param text [String]
+      # @return [Integer]
+      def estimate(text)
+        return 0 unless text.is_a?(String)
+
+        (text.length / CHARS_PER_TOKEN).ceil
+      end
+
+      # Coerce each candidate to an integer (ContextUsage reads its own fields
+      # with this too), accepting integers, numeric strings,
+      # and floats (e.g. a JSON backend emitting 50.0). Truncates via to_i so a
+      # float never raises RangeError; non-numeric values are skipped.
+      def first_positive(*values)
+        values.each do |value|
+          next if value.nil?
+
+          n = Float(value).to_i
+          return n if n.positive?
+        rescue ArgumentError, TypeError
+          next
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/samagotchi/tool_activity.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "log"
+require_relative "tools/execute"
+require_relative "tools/read"
+require_relative "tools/write"
+require_relative "tools/memory"
+require_relative "tools/edit"
+require_relative "tools/task_create"
+require_relative "tools/task_get"
+require_relative "tools/task_list"
+require_relative "tools/task_stop"
+require_relative "tools/task_wait"
+require_relative "tools/web_fetch"
+require_relative "tools/ask_user_question"
+require_relative "tools/list_sessions"
+require_relative "tools/send_note"
+require_relative "tools/delegate"
+require_relative "tools/delegate_result"
+
+module Samagotchi
+  # The one-line summary of a tool call that the UIs show ("reading file",
+  # path="…", ok/error/blocked). Both loops and KernelLoop#dispatch build it
+  # from here. The built-ins have their own words below; any other tool in
+  # the given Tools::Registry gets its entry's label and preview, or
+  # "calling tool" and its arguments as key=value.
+  module ToolActivity
+    TOOL_ACTIVITY_PREVIEW_LIMIT = 80
+
+    module_function
+
+    # @param registry [Tools::Registry, nil] the session's tools
+    def tool_activity_event(tool_name, call, result, registry: nil)
+      {
+        action: tool_activity_action(tool_name, registry: registry),
+        tool: tool_name,
+        params: tool_activity_params(tool_name, call, registry: registry),
+        status: tool_activity_status(result, tool_name)
+      }
+    end
+
+    def tool_activity_action(tool_name, registry: nil)
+      case tool_name
+      when Tools::Execute::NAME then "running command"
+      when Tools::Read::NAME then "reading file"
+      when Tools::Write::NAME then "writing file"
+      when Tools::Edit::NAME then "editing file"
+      when Tools::MemoryRead::NAME then "reading memory"
+      when Tools::MemoryWrite::NAME then "saving memory"
+      when Tools::TaskCreate::NAME then "starting background task"
+      when Tools::TaskGet::NAME then "checking task"
+      when Tools::TaskList::NAME then "listing tasks"
+      when Tools::TaskStop::NAME then "stopping task"
+      when Tools::TaskWait::NAME then "waiting for task"
+      when Tools::WebFetch::NAME then "fetching URL"
+      when Tools::AskUserQuestion::NAME then "asking user"
+      when Tools::ListSessions::NAME then "listing sessions"
+      when Tools::SendNote::NAME then "sending a note"
+      when Tools::Delegate::NAME then "delegating"
+      when Tools::DelegateResult::NAME then "waiting for a delegate"
+      else registry_entry(registry, tool_name)&.label || "calling tool"
+      end
+    end
+
+    # "error" for an "Error:" result, and for an execute whose command
+    # exited non-zero (its last "exit: N" line; no number: killed by a
+    # signal), so the turn tally's "(N failed)" counts it.
+    def tool_activity_status(result, tool_name = nil)
+      text = result.to_s
+      return "error" if text.start_with?("Error:")
+      return "error" if tool_name == Tools::Execute::NAME && execute_failed?(text)
+
+      "ok"
+    end
+
+    def execute_failed?(text)
+      exit_line = text.lines.reverse_each.find { |line| line.start_with?("exit: ") }
+      return false unless exit_line
+
+      code = exit_line[/\Aexit: (\d*)/, 1]
+      code != "0"
+    end
+
+    def tool_activity_params(tool_name, call, registry: nil)
+      case tool_name
+      when Tools::Execute::NAME
+        "command=#{preview_tool_param(call[:content])}"
+      when Tools::Read::NAME
+        parts = ["path=#{preview_tool_param(call[:content])}"]
+        range = format_line_range(call)
+        parts << "lines=#{range}" if range
+        parts.join(" ")
+      when Tools::Write::NAME
+        "path=#{preview_tool_param(call[:path])}"
+      when Tools::Edit::NAME
+        parts = ["path=#{preview_tool_param(call[:path])}"]
+        range = format_line_range(call)
+        parts << "lines=#{range}" if range
+        parts.join(" ")
+      when Tools::MemoryRead::NAME
+        parts = []
+        name = call[:content].to_s.strip
+        parts << "name=#{preview_tool_param(name)}" unless name.empty?
+        scope = call[:scope].to_s.strip
+        parts << "scope=#{preview_tool_param(scope)}" unless scope.empty?
+        parts.join(" ")
+      when Tools::MemoryWrite::NAME
+        parts = []
+        path = call[:path].to_s.strip
+        parts << "name=#{preview_tool_param(path)}" unless path.empty?
+        scope = call[:scope].to_s.strip
+        parts << "scope=#{preview_tool_param(scope)}" unless scope.empty?
+        desc = call[:description].to_s.strip
+        parts << "description=#{preview_tool_param(desc)}" unless desc.empty?
+        parts.join(" ")
+      when Tools::TaskCreate::NAME
+        parts = ["command=#{preview_tool_param(call[:content])}"]
+        cwd = call[:cwd].to_s.strip
+        parts << "cwd=#{preview_tool_param(cwd)}" unless cwd.empty?
+        env = call[:env].to_s.strip
+        parts << "env=#{preview_tool_param(env)}" unless env.empty?
+        parts.join(" ")
+      when Tools::TaskGet::NAME, Tools::TaskStop::NAME
+        "id=#{preview_tool_param(call[:content])}"
+      when Tools::TaskWait::NAME
+        parts = ["id=#{preview_tool_param(call[:content])}"]
+        timeout = call[:timeout].to_s.strip
+        tail_lines = call[:tail_lines].to_s.strip
+        done_pattern = call[:done_pattern].to_s.strip
+        parts << "timeout=#{preview_tool_param(timeout)}" unless timeout.empty?
+        parts << "tail_lines=#{preview_tool_param(tail_lines)}" unless tail_lines.empty?
+        parts << "done_pattern=#{preview_tool_param(done_pattern)}" unless done_pattern.empty?
+        parts.join(" ")
+      when Tools::TaskList::NAME
+        nil
+      when Tools::WebFetch::NAME
+        "url=#{preview_tool_param(call[:content])}"
+      when Tools::ListSessions::NAME
+        call[:cwd].to_s.strip.empty? ? nil : "cwd=#{preview_tool_param(call[:cwd])}"
+      when Tools::SendNote::NAME
+        "session=#{preview_tool_param(call[:session])} text=#{preview_tool_param(call[:content])}"
+      when Tools::Delegate::NAME
+        parts = []
+        parts << "session=#{preview_tool_param(call[:session])}" unless call[:session].to_s.strip.empty?
+        parts << "model=#{preview_tool_param(call[:model])}" unless call[:model].to_s.strip.empty?
+        parts << "task=#{preview_tool_param(call[:content])}"
+        parts << "wait=#{preview_tool_param(call[:wait])}" unless call[:wait].nil? || call[:wait].to_s.strip.empty?
+        parts.join(" ")
+      when Tools::DelegateResult::NAME
+        call[:session].to_s.strip.empty? ? nil : "session=#{preview_tool_param(call[:session])}"
+      when Tools::AskUserQuestion::NAME
+        parts = ["question=#{preview_tool_param(call[:question] || call[:content])}"]
+        opts = call[:options]
+        parts << "options=#{preview_tool_param(Array(opts).join(","))}" if opts && !Array(opts).empty?
+        parts.join(" ")
+      else
+        registry_params(registry_entry(registry, tool_name), call)
+      end
+    end
+
+    def registry_entry(registry, tool_name) = registry && !tool_name.nil? ? registry[tool_name] : nil
+
+    # A plugin tool's label ("chrome: screenshot"), what the UIs show for
+    # its raw name; nil for a built-in, an unknown tool or an empty label.
+    def plugin_label(tool_name, registry:)
+      entry = registry_entry(registry, tool_name)
+      label = entry && !entry.core? ? entry.label.to_s.strip : ""
+      label.empty? ? nil : label
+    end
+
+    # A registry tool's params: its preview, else each given argument as
+    # key="value" (the parsers' args:, which a registry-less reader such as
+    # the web's reload also has); nil for a tool the registry doesn't know
+    # that has no args:, and for a built-in without its own words above
+    # (the reminder tools).
+    def registry_params(entry, call)
+      return nil if entry&.core?
+      return nil if entry.nil? && !call[:args].is_a?(Hash)
+      if entry&.preview
+        begin
+          return entry.preview.call(call)
+        rescue StandardError => e
+          Log.warn(:plugins, "plugin_preview_failed", tool: entry.name, error: e.class.name,
+                                                      msg: "#{entry.name} preview failed: #{e.message}")
+        end
+      end
+
+      given = call[:args].is_a?(Hash) ? call[:args] : call.except(:name)
+      parts = given.filter_map do |key, value|
+        next if value.nil? || value.to_s.strip.empty?
+
+        "#{key}=#{preview_tool_param(value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value)}"
+      end
+      parts.empty? ? nil : parts.join(" ")
+    end
+
+    def format_line_range(call)
+      start_line = call[:start_line].to_s.strip
+      end_line = call[:end_line].to_s.strip
+      return nil if start_line.empty? && end_line.empty?
+
+      "#{start_line.empty? ? "?" : start_line}-#{end_line.empty? ? "?" : end_line}"
+    end
+
+    def preview_tool_param(value)
+      text = value.to_s.gsub(/\s+/, " ").strip
+      return '""' if text.empty?
+
+      if text.length > TOOL_ACTIVITY_PREVIEW_LIMIT
+        text = "#{text[0, TOOL_ACTIVITY_PREVIEW_LIMIT - 1]}…"
+      end
+      text.inspect
+    end
+  end
+end