samagotchi 0.2.0

data/lib/samagotchi/llm/usage.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../token_usage"
+
+module Samagotchi
+  module LLM
+    # A turn's token counts, never nil: what the server reported (:server),
+    # else a chars/4 estimate (:estimate), else zeros (:none).
+    Usage = Data.define(:prompt_tokens, :completion_tokens, :source) do
+      # @return [Usage, nil] nil when the payload carries no counts
+      def self.from_payload(payload)
+        counts = TokenUsage.from_payload(payload)
+        return nil unless counts
+
+        new(prompt_tokens: counts[:prompt_tokens].to_i, completion_tokens: counts[:completion_tokens].to_i,
+            source: :server)
+      end
+
+      # +extra_prompt_tokens+: what the prompt holds besides text (images).
+      def self.estimate(prompt_text:, completion_text:, extra_prompt_tokens: 0)
+        new(prompt_tokens: TokenUsage.estimate(prompt_text.to_s) + extra_prompt_tokens.to_i,
+            completion_tokens: TokenUsage.estimate(completion_text.to_s),
+            source: :estimate)
+      end
+
+      def self.none = new(prompt_tokens: 0, completion_tokens: 0, source: :none)
+
+      def total_tokens = prompt_tokens + completion_tokens
+    end
+
+    # Builds a turn's Usage from its stream events, the way SessionMetrics
+    # counts them: server counts are cumulative per request, so each
+    # generation keeps its highest; the prompt grows across a turn's
+    # generations, so the last generation's prompt counts, and completions
+    # add up. Without server counts, the streamed text is estimated.
+    class UsageCollector
+      def initialize
+        @generations = []
+      end
+
+      def observe(event)
+        case event[:type]
+        when :generation_started
+          @generations << { prompt: 0, completion: 0, server: false, text: +"" }
+        when :generation_chunk
+          @generations << { prompt: 0, completion: 0, server: false, text: +"" } if @generations.empty?
+          record(@generations.last, event)
+        end
+      end
+
+      # @param prompt_text [String, nil] what an estimate counts as the prompt
+      # @param extra_prompt_tokens [Integer] estimated non-text prompt tokens
+      def usage(prompt_text: nil, extra_prompt_tokens: 0)
+        server = @generations.select { |generation| generation[:server] }
+        unless server.empty?
+          return Usage.new(prompt_tokens: server.last[:prompt], completion_tokens: server.sum { |g| g[:completion] },
+                           source: :server)
+        end
+
+        text = @generations.sum("") { |generation| generation[:text] }
+        return Usage.none if text.empty?
+
+        Usage.estimate(prompt_text: prompt_text, completion_text: text, extra_prompt_tokens: extra_prompt_tokens)
+      end
+
+      private
+
+      def record(generation, event)
+        counts = Usage.from_payload(event[:payload])
+        if counts
+          generation[:server] = true
+          generation[:prompt] = [generation[:prompt], counts.prompt_tokens].max
+          generation[:completion] = [generation[:completion], counts.completion_tokens].max
+        end
+        generation[:text] << event[:content].to_s
+      end
+    end
+  end
+end

data/lib/samagotchi/log.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "log_line"
+require_relative "debug_log"
+
+module Samagotchi
+  autoload :Config, File.expand_path("config", __dir__)
+  autoload :LogPath, File.expand_path("log_path", __dir__)
+
+  # The one logging facade: tagged, levelled records in the debug log
+  # (LogPath, format in LogLine), one process-wide sink.
+  #
+  #   Log.info(:worker, "idle_exit", idle_s: 1800)
+  #   Log.warn(:hooks, "hook_failed", echo: "[samagotchi:hooks] …")
+  #   Log.debug(:model, "response", payload: text, model: "qwen")
+  #
+  # echo: is for what used to be a plain `warn`: that text still goes to
+  # stderr unchanged (whatever the level; not in a worker, see configure)
+  # and becomes the record's msg= field.
+  #
+  # Unconfigured, the first record resolves the file and level from Config
+  # (once, until Config.reload!). While that runs (Config can warn itself)
+  # records only echo. Nothing here raises into the caller: a record that
+  # can't be formatted is dropped, an unwritable file pauses (DebugLog).
+  module Log
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+    DEFAULT_LEVEL = :info
+    MAX_PAYLOAD_BYTES = 64 * 1024
+    SID_LENGTH = 8
+    BACKTRACE_FRAMES = 20
+    # A field named like a credential never shows its value. Whole name
+    # segments, so counts like prompt_tokens stay readable.
+    SECRET_KEY = /(?:\A|_)(?:key|api_?key|token|secret|authorization|auth|password|passwd|cookie)(?:\z|_)/
+    URL = %r{\A[a-z][a-z0-9+.-]*://}i
+
+    @monitor = Monitor.new
+    @options = {}
+    @state = nil
+    @resolving = false
+    @session_id = nil
+
+    class << self
+      # @param path [String, nil, :auto] the file; :auto → LogPath.resolve
+      # @param level [Symbol, String, nil] nil → log.level
+      # @param stderr [Boolean] false in a worker: echo: text goes nowhere
+      #   (its stderr is /dev/null anyway), only to the file
+      # @param mirror [Boolean] -v: every record written also goes to stderr
+      def configure(path: :auto, level: nil, stderr: true, mirror: false)
+        @monitor.synchronize do
+          close_state
+          @options = { path: path, level: level, stderr: stderr, mirror: mirror }
+        end
+        self
+      end
+
+      # Back to unconfigured (specs: before each example).
+      def reset!
+        @monitor.synchronize do
+          close_state
+          @options = {}
+          @session_id = nil
+        end
+      end
+
+      # Config changed (Config.reload!): resolve :auto parts again.
+      def invalidate!
+        @monitor.synchronize { close_state }
+      end
+
+      # The session this process works for (a worker, the REPL); records
+      # carry its first SID_LENGTH chars unless they pass their own sid:.
+      attr_accessor :session_id
+
+      def debug(tag, event, **kw) = log(:debug, tag, event, **kw)
+      def info(tag, event, **kw) = log(:info, tag, event, **kw)
+      def warn(tag, event, **kw) = log(:warn, tag, event, **kw)
+      def error(tag, event, **kw) = log(:error, tag, event, **kw)
+
+      # ERROR with the exception and its first BACKTRACE_FRAMES frames as
+      # the payload (crashes of threads and workers).
+      def exception(tag, event, error, echo: nil, **fields)
+        frames = Array(error.backtrace).first(BACKTRACE_FRAMES)
+        log(:error, tag, event, echo: echo, payload: frames.join("\n"),
+                                error: error.class.name, msg: error.message.to_s[0, 500], **fields)
+      end
+
+      # Whether a record at this level reaches the file or stderr (to skip
+      # building a big payload for nothing).
+      def level?(level)
+        state = resolved_state
+        state ? LEVELS.fetch(level.to_sym) >= state[:level] : false
+      end
+
+      def path
+        resolved_state&.dig(:writer)&.path
+      end
+
+      def log(level, tag, event, payload: nil, sid: nil, echo: nil, **fields)
+        options = @options
+        echo_to_stderr(echo) if echo && options.fetch(:stderr, true)
+        state = resolved_state
+        return nil unless state && LEVELS.fetch(level) >= state[:level]
+
+        fields = { msg: echo }.merge(fields) if echo && !fields.key?(:msg)
+        text = build(level, tag, event, payload: payload, sid: sid || @session_id, fields: fields)
+        return nil unless text
+
+        state[:writer].write(text)
+        mirror(text) if state[:mirror] && !echo
+        text
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def build(level, tag, event, payload:, sid:, fields:)
+        tag = tag.to_s
+        event = event.to_s
+        raise ArgumentError, "unknown log tag #{tag}" unless LogLine::TAGS.include?(tag)
+        raise ArgumentError, "bad log event #{event}" unless event.match?(LogLine::SLUG)
+
+        fields = fields.each_with_object({}) do |(key, value), out|
+          key = key.to_s
+          next if value.nil? || !key.match?(LogLine::KEY)
+
+          out[key] = safe_value(key, value)
+        end
+        payload = payload.to_s if payload
+        if payload && payload.bytesize > MAX_PAYLOAD_BYTES
+          fields["truncated"] = payload.bytesize - MAX_PAYLOAD_BYTES
+          payload = payload.byteslice(0, MAX_PAYLOAD_BYTES)
+        end
+        LogLine.format(LogLine::Record.new(
+          ts: Time.now, level: level.to_s.upcase, tag: tag, pid: Process.pid,
+          sid: sid && sid.to_s[0, SID_LENGTH], event: event, fields: fields, payload: payload
+        ))
+      rescue StandardError
+        nil
+      end
+
+      def safe_value(key, value)
+        return "[redacted]" if key.match?(SECRET_KEY)
+
+        value = value.is_a?(Float) ? value.round(3) : value
+        value.is_a?(String) && value.match?(URL) ? safe_url(value) : value
+      end
+
+      # No userinfo, no query or fragment (keys ride there sometimes).
+      def safe_url(url)
+        url.sub(%r{\A([a-z][a-z0-9+.-]*://)[^/?#@]*@}i, "\\1").sub(/[?#].*\z/m, "")
+      end
+
+      def echo_to_stderr(text)
+        $stderr.puts(text)
+      rescue StandardError
+        nil
+      end
+
+      def mirror(text)
+        $stderr.write(text)
+      rescue StandardError
+        nil
+      end
+
+      def resolved_state
+        state = @state
+        return state if state
+
+        @monitor.synchronize do
+          return @state if @state
+          # Config.get below may log a warning: that one only echoes.
+          return nil if @resolving
+
+          @resolving = true
+          begin
+            @state = build_state
+          ensure
+            @resolving = false
+          end
+        end
+      end
+
+      def build_state
+        options = @options
+        path = options.fetch(:path, :auto)
+        path = (LogPath.resolve rescue nil) if path == :auto
+        level = options[:level] || (Config.get("log.level") rescue nil)
+        level = LEVELS.key?(level.to_s.downcase.to_sym) ? level.to_s.downcase.to_sym : DEFAULT_LEVEL
+        { writer: DebugLog.new(path: path), level: LEVELS.fetch(level), mirror: options[:mirror] ? true : false }
+      end
+
+      def close_state
+        @state&.dig(:writer)&.close
+        @state = nil
+      end
+    end
+  end
+end

data/lib/samagotchi/log_line.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Samagotchi
+  # The debug log's line format: the one contract between the writer (Log)
+  # and every reader (the web's later log view, `chi log`, grep and awk).
+  #
+  #   <ts> <LEVEL> <tag> pid=<n> [sid=<8>] <event> [k=v ...]
+  #       <payload line>
+  #
+  # ts is UTC ISO8601 with milliseconds, LEVEL is padded to 5, tag and event
+  # are slugs. A value is bare when it has no space, quote or `=`, else a
+  # JSON string, so a newline in a value never splits a record. Payload lines
+  # (debug dumps) are indented by four spaces and belong to the record above.
+  module LogLine
+    LEVELS = %w[DEBUG INFO WARN ERROR].freeze
+    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model].freeze
+    INDENT = "    "
+
+    Record = Struct.new(:ts, :level, :tag, :pid, :sid, :event, :fields, :payload, keyword_init: true)
+
+    SLUG = /\A[a-z0-9_.-]+\z/
+    KEY = /\A[a-z0-9_]+\z/
+    BARE = /\A[^"=\p{Z}\p{Cc}\p{Cf}]+\z/
+    HEADER = /\A(?<ts>\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z) (?<level>DEBUG|INFO|WARN|ERROR) +(?<tag>[a-z]+) pid=(?<pid>\d+)(?: sid=(?<sid>[^\s"=]+))? (?<event>[a-z0-9_.-]+)(?<rest>.*)\z/
+    FIELD = /\G (?<key>[a-z0-9_]+)=(?:"(?<quoted>(?:[^"\\]|\\.)*)"|(?<bare>[^\s"=]+))/
+    # C1 controls and the line/paragraph separators JSON.generate leaves as is.
+    EXTRA_ESCAPES = /[\u007f-\u009f\u2028\u2029]/
+
+    module_function
+
+    # The record as one string: header, payload lines, trailing newline.
+    def format(record)
+      head = [format_ts(record.ts), record.level.to_s.upcase.ljust(5), record.tag.to_s, "pid=#{record.pid}"]
+      head << "sid=#{record.sid}" if record.sid && !record.sid.to_s.empty?
+      head << record.event.to_s
+      line = +head.join(" ")
+      (record.fields || {}).each { |key, value| line << " #{key}=#{format_value(value)}" unless value.nil? }
+      line << "\n"
+      payload = record.payload
+      line << format_payload(payload) if payload && !payload.to_s.empty?
+      line
+    end
+
+    def format_ts(time)
+      return time if time.is_a?(String)
+
+      time.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+
+    def format_value(value)
+      text = clean(value.to_s)
+      return text if text.match?(BARE)
+
+      JSON.generate(text).gsub(EXTRA_ESCAPES) { |c| Kernel.format("\\u%04x", c.ord) }
+    end
+
+    # Every payload line indented; control characters (ANSI colours from a
+    # tool, a stray \r) shown escaped so the log can be cat'ed safely.
+    def format_payload(payload)
+      clean(payload.to_s).split("\n", -1).map { |line| "#{INDENT}#{escape_controls(line.chomp("\r"))}\n" }.join
+    end
+
+    def escape_controls(text)
+      text.gsub(/[\p{Cc}&&[^\t]]|#{EXTRA_ESCAPES}/o) { |c| c == "\e" ? "\\e" : Kernel.format("\\u%04x", c.ord) }
+    end
+
+    # Valid UTF-8 whatever the source (binary tool output included).
+    def clean(text)
+      text = text.dup.force_encoding(Encoding::UTF_8) unless text.encoding == Encoding::UTF_8
+      text.valid_encoding? ? text : text.scrub("?")
+    end
+
+    # One header line → Record (payload nil), or nil when it isn't one.
+    def parse(line)
+      match = HEADER.match(line.to_s.chomp)
+      return nil unless match
+
+      fields = parse_fields(match[:rest])
+      return nil unless fields
+
+      Record.new(ts: match[:ts], level: match[:level], tag: match[:tag], pid: Integer(match[:pid]),
+                 sid: match[:sid], event: match[:event], fields: fields, payload: nil)
+    end
+
+    def parse_fields(rest)
+      fields = {}
+      pos = 0
+      while pos < rest.length
+        m = FIELD.match(rest, pos)
+        return nil unless m && m.begin(0) == pos
+
+        fields[m[:key]] = m[:quoted] ? JSON.parse("[\"#{m[:quoted]}\"]").first : m[:bare]
+        pos = m.end(0)
+      end
+      fields
+    rescue JSON::ParserError
+      nil
+    end
+
+    def payload_line?(line)
+      line.start_with?(INDENT)
+    end
+
+    # Yields each Record of a log (payload lines joined onto theirs). Lines
+    # that are neither (an older format, a torn write) go to on_invalid.
+    def each_record(io, on_invalid: nil)
+      return enum_for(:each_record, io, on_invalid: on_invalid) unless block_given?
+
+      current = nil
+      io.each_line do |raw|
+        line = clean(raw).chomp
+        if current && payload_line?(line)
+          text = line.delete_prefix(INDENT)
+          current.payload = current.payload ? "#{current.payload}\n#{text}" : text
+          next
+        end
+        yield current if current
+        current = parse(line)
+        on_invalid&.call(line) if current.nil? && !line.empty?
+      end
+      yield current if current
+    end
+  end
+end

data/lib/samagotchi/log_path.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Samagotchi
+  # Where the debug log (DebugLog) goes, for the REPL, the attached terminal
+  # and the background worker alike: nil when log.disable is set, else log.file
+  # (~ and relative paths expanded against cwd), else
+  # $XDG_STATE_HOME/samagotchi/samagotchi.log (~/.local/state/... by default),
+  # next to the sessions and prompt history. Never inside the gem or checkout.
+  module LogPath
+    FILENAME = "samagotchi.log"
+
+    module_function
+
+    def resolve(env: ENV)
+      return nil if Config.get("log.disable")
+
+      configured = Config.get("log.file").to_s.strip
+      return File.expand_path(configured) unless configured.empty?
+
+      default_path(env: env)
+    end
+
+    def default_path(env: ENV)
+      xdg = env.fetch("XDG_STATE_HOME", "").to_s.strip
+      base = xdg.empty? ? File.join(Dir.home, ".local", "state") : xdg
+      File.join(base, "samagotchi", FILENAME)
+    end
+  end
+end

data/lib/samagotchi/log_subscriber.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative "log"
+
+module Samagotchi
+  # The event trail: a SessionObserver subscriber (next to SessionMetrics)
+  # that writes what happened in a session, in order, as `turn` records.
+  # Both loops (native and chat) emit the same vocabulary, so every host
+  # leaves the same trail. Event names are the observer's types.
+  #
+  # INFO carries sizes and timings, never the text of a prompt, answer or
+  # tool output (DEBUG dumps are KernelLoop's). It runs under the observer's
+  # lock: it only formats and appends (Log never blocks on rotation).
+  class LogSubscriber
+    TAG = :turn
+    # One line each, with a few of their own fields (never text).
+    ANNOUNCED = {
+      turn_enqueued: %i[enqueued_id client_id],
+      command_queued: %i[command_id client_id],
+      command_ran: %i[command_id client_id status],
+      input_merged: %i[count],
+      prompt_restored: [],
+      continue_offered: %i[no_interrupt],
+      continue_resolved: [],
+      context_added: %i[note_id source],
+      reminder_injected: [],
+      question_requested: [],
+      question_answered: %i[id],
+      question_cancelled: %i[id reason],
+      pending_input_merged: %i[iteration count],
+      generation_cancelled: %i[iteration]
+    }.freeze
+
+    # @param session_id [#call] the session the events are about (the
+    #   Engine's current one), as the records' sid
+    def initialize(session_id: -> {}, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @session_id = session_id
+      @clock = clock
+      @turn_started_at = nil
+      @generation_started_at = {}
+      @tool_started_at = {}
+    end
+
+    def call(event)
+      type = event[:type]&.to_sym
+      return unless type
+
+      if respond_to?(handler = :"on_#{type}", true)
+        send(handler, event)
+      elsif ANNOUNCED.key?(type)
+        log(:info, type, **event.slice(*ANNOUNCED[type]), **origin(event), **items(event))
+      end
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def on_turn_started(event)
+      @turn_started_at = @clock.call
+      @generation_started_at.clear
+      @tool_started_at.clear
+      log(:info, :turn_started, session: event[:session_id], prompt_chars: event[:prompt].to_s.length,
+                                continue: event[:continue] || nil, **items(event), **origin(event))
+    end
+
+    def on_turn_completed(event)
+      summary = event[:turn_summary] || {}
+      log(:info, :turn_completed, ms: since(@turn_started_at), result_chars: summary[:output].to_s.length,
+                                  tools: Array(summary[:tool_activity]).size,
+                                  exhausted: summary[:exhausted] || nil, **origin(event))
+    end
+
+    def on_turn_canceled(event)
+      log(:info, :turn_canceled, ms: since(@turn_started_at), reason: event[:cancellation_reason], **origin(event))
+    end
+
+    def on_turn_failed(event)
+      log(:warn, :turn_failed, ms: since(@turn_started_at), error: event[:error_class], error_kind: event[:error_kind],
+                               host: event[:host], retryable: event[:retryable],
+                               msg: (event[:summary] || event[:message]).to_s[0, 300], **origin(event))
+    end
+
+    def on_generation_started(event)
+      @generation_started_at[event[:iteration]] = @clock.call
+      log(:debug, :generation_started, iteration: event[:iteration], profile: event[:profile],
+                                       context_window: event[:context_window_tokens])
+    end
+
+    def on_generation_completed(event)
+      log(:info, :generation_completed, iteration: event[:iteration],
+                                        ms: since(@generation_started_at.delete(event[:iteration])),
+                                        served_model: event[:served_model], requested_model: event[:requested_model],
+                                        content_length: event[:content_length],
+                                        thinking_chars: event[:thinking_chars])
+    end
+
+    def on_generation_retrying(event)
+      log(:warn, :generation_retrying, iteration: event[:iteration], attempt: event[:attempt],
+                                       max_retries: event[:max_retries], delay_s: event[:next_delay],
+                                       error: event[:error_class], msg: event[:error_message].to_s[0, 300])
+    end
+
+    def on_tool_call_started(event)
+      @tool_started_at[[event[:iteration], event[:call_index]]] = @clock.call
+    end
+
+    def on_tool_call_completed(event)
+      # A tool's output can be any bytes (invalid UTF-8 would fail the match).
+      output = event[:output].to_s.scrub
+      log(:info, :tool_call_completed, iteration: event[:iteration], tool: event[:tool],
+                                       ms: since(@tool_started_at.delete([event[:iteration], event[:call_index]])),
+                                       output_chars: output.length, truncated: event[:output_truncated] || nil,
+                                       error: tool_error?(output) || nil)
+    end
+
+    def on_guardrail_warning(event)
+      log(:warn, :guardrail_warning, label: event[:label], msg: event[:message].to_s[0, 300])
+    end
+
+    # A hook's notice to the user: who said it and what (its text is the
+    # hook's, not the user's or the model's).
+    def on_hook_notice(event)
+      level = event[:level].to_s == "warn" ? :warn : :info
+      log(level, :hook_notice, hook: event[:hook], msg: event[:text].to_s[0, 300])
+    end
+
+    # A card shown to the user (Engine#show_card): whose, which, and its
+    # title (the body is the plugin's text; not logged).
+    def on_card(event)
+      log(:info, :card, source: event[:source], id: event[:id], actions: Array(event[:actions]).size,
+                        msg: event[:title].to_s[0, 300])
+    end
+
+    def on_recap_ready(event)
+      log(:info, :recap_ready, chars: event[:recap].to_s.length, generation: event[:generation], covered: event[:covered])
+    end
+
+    # "[read] Error: …" (the dispatch failed) or "[read]\nError: …" (the
+    # tool said so), and an unknown tool's bare "Error: …".
+    def tool_error?(output)
+      output.match?(/\A(?:\[[^\]\n]*\]\s*)?Error:/)
+    end
+
+    def origin(event)
+      client = event.dig(:origin, :client_id) if event[:origin].is_a?(Hash)
+      client ? { client_id: client } : {}
+    end
+
+    def items(event)
+      images = Array(event[:images]).size
+      images.positive? ? { images: images } : {}
+    end
+
+    def since(started)
+      started ? ((@clock.call - started) * 1000).round : nil
+    end
+
+    def log(level, event, **fields)
+      Log.public_send(level, TAG, event, sid: @session_id.call, **fields)
+    end
+  end
+end