samagotchi 0.139.1 → 0.141.0

data/lib/samagotchi/context_judge.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "context_candidates_log"
+require_relative "log"
+require_relative "system_one/question"
+
+module Samagotchi
+  # System 1's judgment of a session's candidate context
+  # (docs/context.md, "The judge"): is this session's work about the
+  # candidate? One ask per candidate, its state neutral and small: the
+  # candidate's title (and describe), the owner's own prompts (the first
+  # substantive one and the latest, each bounded) and, for a delegate
+  # child, what its parent session has attached. Never the branch or the
+  # checkout (bare place facts), never the source's why, never "found for
+  # this checkout". The instructions are constant (one for a session, one
+  # for a delegate child): the candidate is in the state, so the server's
+  # prefix cache holds and nothing a plugin wrote is read as instructions.
+  #
+  # The same ask has a second question, "Has the user stated a task yet?":
+  # under TASK_MIN the candidate stays unjudged and is asked again at the
+  # next owner prompt. After a judged ask, one re-ask once
+  # context.candidates.reask_after_turns more owner prompts came, then
+  # done (#due?). What it asked and answered is a `judged` line in
+  # ContextCandidatesLog. In on mode ContextCandidateChoice acts on it
+  # (attach, card, or nothing); audit only logs.
+  module ContextJudge
+    MODES = %w[off audit on].freeze
+    ABOUT_ID = "about"
+    TASK_ID = "task"
+    # The bound on each prompt in the state.
+    PROMPT_MAX = 1500
+    # Below this the user hasn't stated a task yet: the ask is deferred.
+    TASK_MIN = 0.5
+    # A prompt of this many words or fewer is not the first substantive one
+    # while a longer one follows (#conversation).
+    SHORT_WORDS = 3
+    ABOUT = "A user works with a coding agent session. The state names a candidate source of context and the " \
+            "user's messages in the session so far (the first one with a task, and the latest). " \
+            "Is this session's work about the candidate? Work on something else is not."
+    CHILD = " This session was started by another agent session: the conversation's first message is that " \
+            "session's request, and started_from lists what that session has attached (the work it is doing)."
+    TASK = "A user works with a coding agent session; the state holds the user's messages so far. " \
+           "Has the user stated a task yet? A greeting or small talk alone is not one."
+
+    # One ask's snapshot, taken on the turn's (or the plugin's) thread.
+    # +conversation+ is the owner's prompts as the state carries them,
+    # +parent_attached+ nil unless the session is a delegate child,
+    # +owner_prompts+ how many owner prompts the session had (the re-ask
+    # counts them), +phase+ "turn" (a turn's start or end) or "late" (a
+    # proposal after the prompts).
+    Job = Data.define(:session_id, :name, :title, :describe, :conversation, :parent_attached, :owner_prompts, :phase)
+    # The thresholds a judged line's would is read with, and the mode.
+    Settings = Data.define(:mode, :threshold, :offer_threshold, :reask_after_turns) do
+      def self.from_config
+        new(mode: ContextJudge.mode, threshold: Config.get("context.candidates.threshold").to_f,
+            offer_threshold: Config.get("context.candidates.offer_threshold").to_f,
+            reask_after_turns: [Config.get("context.candidates.reask_after_turns").to_i, 1].max)
+      end
+    end
+
+    module_function
+
+    # context.candidates.mode: off (the default: no conversation text goes
+    # to a System 1 host), audit or on. An unknown value reads as off.
+    def mode
+      value = Config.get("context.candidates.mode").to_s.strip.downcase
+      MODES.include?(value) ? value : "off"
+    end
+
+    # The bounded conversation the state carries: the first substantive
+    # owner prompt and the latest (one when they are the same). +skip+
+    # owner prompts at the start are not substantive (an earlier ask said
+    # no task was stated in them), nor is a short one (SHORT_WORDS words or
+    # fewer: "hi", "ok go") while a longer one follows, as the earlier
+    # prompts may have come before any candidate was there to ask about. A
+    # delegate child (+child+) keeps its first: the parent's request.
+    # @param texts [Array<String>] the owner's prompts, oldest first
+    # @return [Array<String>]
+    def conversation(texts, skip: 0, child: false)
+      texts = Array(texts).map(&:to_s).reject { |text| text.strip.empty? }
+      return [] if texts.empty?
+
+      first = child ? 0 : first_substantive(texts, skip)
+      picked = first == texts.size - 1 ? [texts.last] : [texts[first], texts.last]
+      picked.map { |text| bound(text) }
+    end
+
+    def first_substantive(texts, skip)
+      from = skip < texts.size ? skip : 0
+      (from...texts.size).find { |index| texts[index].split.size > SHORT_WORDS } || from
+    end
+
+    def bound(text)
+      text = text.strip
+      text.length > PROMPT_MAX ? "#{text[0, PROMPT_MAX - 1]}…" : text
+    end
+
+    # The ask's state.
+    # @return [Hash{String => Object}]
+    def state(job)
+      candidate = job.describe.to_s.strip.empty? ? job.title : "#{job.title} — #{job.describe}"
+      state = { "candidate" => candidate, "conversation" => job.conversation }
+      state["started_from"] = { "parent_attached" => job.parent_attached } if job.parent_attached
+      state
+    end
+
+    # The two questions, constant for a session (+child+: a delegate child).
+    def questions(child:)
+      { ABOUT_ID => SystemOne::Question.new(id: ABOUT_ID, type: "noul", instructions: child ? ABOUT + CHILD : ABOUT),
+        TASK_ID => SystemOne::Question.new(id: TASK_ID, type: "noul", instructions: TASK) }
+    end
+
+    # How many owner prompts at the start no ask found a task in: the
+    # latest deferred ask's count (any candidate of the session).
+    def skip(records)
+      records.select { |line| line["kind"] == "judged" && line["stated"] == false }
+             .map { |line| line["owner_prompts"].to_i }.max || 0
+    end
+
+    # Whether candidate +name+ is asked now, at +owner_prompts+: never twice
+    # at one count; unjudged (no ask, or only deferred ones) → yes; one
+    # judged ask → once +reask_after_turns+ more owner prompts came; two →
+    # done.
+    def due?(records, name, owner_prompts:, reask_after_turns:)
+      mine = records.select { |line| line["kind"] == "judged" && line["name"] == name }
+      return false if mine.any? { |line| line["owner_prompts"].to_i >= owner_prompts }
+
+      judged = mine.select { |line| line["stated"] == true }
+      return true if judged.empty?
+      return false if judged.size >= 2
+
+      owner_prompts >= judged.first["owner_prompts"].to_i + reask_after_turns
+    end
+
+    # The proposed candidates due an ask (+rows+: ContextCandidates
+    # .with_status), as Jobs. +texts+ the owner's prompts, oldest first;
+    # +parent_attached+ the parent's sources' titles for a delegate child,
+    # else nil.
+    # @return [Array<Job>]
+    def jobs(rows, records, session_id:, texts:, parent_attached:, settings:, phase:)
+      owner_prompts = texts.size
+      return [] if owner_prompts.zero?
+
+      conversation = conversation(texts, skip: skip(records), child: !parent_attached.nil?)
+      rows.filter_map do |candidate, status|
+        next unless status == "proposed"
+        next unless due?(records, candidate.name, owner_prompts: owner_prompts,
+                                                  reask_after_turns: settings.reask_after_turns)
+
+        Job.new(session_id: session_id, name: candidate.name, title: candidate.title, describe: candidate.describe,
+                conversation: conversation, parent_attached: parent_attached, owner_prompts: owner_prompts,
+                phase: phase)
+      end
+    end
+
+    # What on mode would do with +p+: attach (≥ threshold), offer (≥
+    # offer_threshold) or none.
+    def would(probability, settings)
+      return "attach" if probability >= settings.threshold
+      return "offer" if probability >= settings.offer_threshold
+
+      "none"
+    end
+
+    # One ask (on SideJudgments' thread) and its judged line. No answer
+    # (System 1 said nothing: its own warn) writes nothing, so the
+    # candidate is asked again at the next owner prompt.
+    # @return [Hash, nil] the line's fields
+    def ask(client:, job:, log:, settings:, cancel_controller: nil)
+      answers = client.ask(state: state(job), questions: questions(child: !job.parent_attached.nil?),
+                           cancel_controller: cancel_controller)
+      about = answers&.dig(ABOUT_ID)&.noul
+      task = answers&.dig(TASK_ID)&.noul
+      return nil if about.nil? || task.nil?
+
+      stated = task >= TASK_MIN
+      fields = { "title" => job.title, "phase" => job.phase, "owner_prompts" => job.owner_prompts,
+                 "p" => about.round(4), "task_p" => task.round(4), "stated" => stated,
+                 "would" => stated ? would(about, settings) : nil, "mode" => settings.mode,
+                 "threshold" => settings.threshold, "offer_threshold" => settings.offer_threshold,
+                 "host" => client.host, "model" => client.model, "child" => job.parent_attached ? true : nil,
+                 "conversation" => job.conversation.map { |text| ContextCandidatesLog.short(text) } }
+      ContextCandidatesLog.event("judged", session_id: job.session_id, name: job.name, log: log, **fields.transform_keys(&:to_sym))
+      fields
+    end
+
+    def warn(error)
+      Log.warn(:context, "context_judge_failed",
+               echo: "[samagotchi:context] candidate judge: #{error.class}: #{error.message}",
+               error: error.class.name, msg: error.message.to_s[0, 200])
+    end
+  end
+end

data/lib/samagotchi/context_move.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "context_sources"
+require_relative "session_inbox"
+require_relative "log"
+
+module Samagotchi
+  # Movable context on its two paths, a continue (SessionContinue) and a
+  # plugin fork (ctx.sessions.fork): from SessionManager.spawn_session's
+  # before_spawn, once the new session and its first note are saved and
+  # before its worker starts, so its first absorb sees the sources.
+  module ContextMove
+    # What the new session's note says it is from.
+    NOTE_SOURCE = "attached context"
+
+    # ContextSources.move, then a second note in the new session saying what
+    # moved and what stayed (named by time, it sorts after the first). Best
+    # effort: a failure is logged and the session starts without (its start
+    # must not be undone for it).
+    # @return [ContextSources::Moved]
+    def self.call(from:, to:, mode:, state_dir:, seed: nil)
+      moved = ContextSources.move(from: from, to: to, mode: mode, seed: seed, state_dir: state_dir)
+      text = moved.note_text(from)
+      SessionInbox.write_note(to, text: text, source: NOTE_SOURCE, state_dir: state_dir) if text
+      moved
+    rescue StandardError => e
+      Log.warn(:context, "context_move_failed", sid: to, from: from, error: e.class.name, msg: e.message.to_s[0, 200])
+      ContextSources::Moved.none
+    end
+  end
+end

data/lib/samagotchi/context_report_command.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "time"
+
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "config"
+require_relative "context_candidates_log"
+require_relative "session"
+
+module Samagotchi
+  # `chi context report [--days N]`: counts from context_candidates.jsonl
+  # (ContextCandidatesLog), no prompts: what was proposed and mentioned,
+  # the judge's asks, what it would attach at each threshold, and how that
+  # agrees with what the user did with the same candidates (attached,
+  # mentioned, or declined); on mode's attaches (and how many the user
+  # removed later), cards and /context attach|decline. This machine only
+  # (SessionAccess::Contract).
+  class ContextReportCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi context report [--days N]
+        Counts from the candidate judge's log (context_candidates.jsonl): candidates
+        proposed, mentioned, attached or declined by you, withdrawn; the judge's asks
+        (judged, or no task stated yet); how many candidates it would attach at each
+        threshold (each candidate's latest judged ask); and how that agrees with what
+        you did with them. On mode: the judge's attaches, how many you removed later,
+        its cards, and /context attach|decline. Default: the last 14 days.
+    TEXT
+
+    DEFAULT_DAYS = 14
+    THRESHOLDS = [0.5, 0.6, 0.7, 0.8, 0.9].freeze
+    FLAGS = CLI::Flags.new(args: false) { |flags| flags.value "--days" }.freeze
+
+    # @param argv [Array<String>] the arguments after "context report"
+    # @param state_dir [String, nil] the sessions folder (a spec seam)
+    # @param now [Time] the report's clock (a spec seam)
+    def initialize(argv, stdout: $stdout, stderr: $stderr, state_dir: nil, now: Time.now)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @state_dir = state_dir || Session.default_state_dir
+      @now = now
+    end
+
+    def run
+      parsed = parse_flags(FLAGS, @argv)
+      return parsed if parsed.is_a?(Integer)
+
+      days = parsed.options[:days]
+      return usage_error("--days takes a positive whole number") if days && !days.to_s.match?(/\A[1-9]\d*\z/)
+
+      report(days ? Integer(days, 10) : DEFAULT_DAYS)
+      CLI::Exit::OK
+    end
+
+    # The counts, as a Hash (the report prints these).
+    def self.counts(records, threshold:, offer_threshold:)
+      by_candidate = records.group_by { |line| [line["session_id"], line["name"]] }
+      kinds = ->(kind) { records.count { |line| line["kind"] == kind } }
+      judged = records.select { |line| line["kind"] == "judged" }
+      latest = by_candidate.transform_values do |lines|
+        lines.reverse.find { |line| line["kind"] == "judged" && line["stated"] == true }&.fetch("p", nil)
+      end.compact
+      choices = by_candidate.transform_values { |lines| user_choice(lines) }.compact
+      {
+        sessions: records.map { |line| line["session_id"] }.uniq.size,
+        proposed: kinds.call("proposed"), mentioned: kinds.call("mentioned"), attached: kinds.call("attached"),
+        declined: kinds.call("declined"), detached: kinds.call("detached"), withdrawn: kinds.call("withdrawn"),
+        asks: judged.size, stated: judged.count { |line| line["stated"] == true },
+        unstated: judged.count { |line| line["stated"] == false }, candidates_judged: latest.size,
+        would: THRESHOLDS.to_h { |t| [t, latest.values.count { |p| p.to_f >= t }] },
+        threshold: threshold, offer_threshold: offer_threshold,
+        agreement: agreement(latest, choices, threshold)
+      }.merge(on_mode(records, by_candidate))
+    end
+
+    # On mode's own lines: the judge's attaches, those the user removed
+    # later (its false positives), the cards, and /context attach|decline.
+    def self.on_mode(records, by_candidate)
+      by_command = ->(kind) { records.count { |line| line["kind"] == kind && line["by"] == "command" } }
+      removed = by_candidate.values.count do |lines|
+        index = lines.index { |line| line["kind"] == "judge_attached" }
+        index && lines.drop(index + 1).any? { |line| %w[declined detached].include?(line["kind"]) && line["by"] != "command" }
+      end
+      { judge_attached: records.count { |line| line["kind"] == "judge_attached" }, judge_removed: removed,
+        carded: records.count { |line| line["kind"] == "carded" }, command_attached: by_command.call("attached"),
+        command_declined: by_command.call("declined") }
+    end
+
+    # What the user last did with a candidate: "attached" (attached by
+    # them, or mentioned) or "declined"; nil when neither.
+    def self.user_choice(lines)
+      last = lines.reverse.find { |line| %w[mentioned attached declined detached].include?(line["kind"]) }
+      return nil if last.nil? || last["kind"] == "detached"
+
+      last["kind"] == "declined" ? "declined" : "attached"
+    end
+
+    # The judged candidates the user also chose for: agree (would attach
+    # what they attached, or not what they declined), attached what they
+    # declined, missed what they attached.
+    def self.agreement(latest, choices, threshold)
+      both = latest.keys & choices.keys
+      result = { candidates: both.size, agree: 0, wrong_attach: 0, missed: 0 }
+      both.each do |key|
+        would = latest[key].to_f >= threshold
+        if would == (choices[key] == "attached") then result[:agree] += 1
+        elsif would then result[:wrong_attach] += 1
+        else result[:missed] += 1
+        end
+      end
+      result
+    end
+
+    private
+
+    def command_name = "chi context report"
+
+    def report(days)
+      cutoff = @now - (days * 86_400)
+      records = ContextCandidatesLog.log_for(@state_dir).records.select { |line| after?(line["at"], cutoff) }
+      counts = self.class.counts(records, threshold: Config.get("context.candidates.threshold").to_f,
+                                          offer_threshold: Config.get("context.candidates.offer_threshold").to_f)
+      print_counts(counts, days)
+    end
+
+    def after?(iso, cutoff)
+      Time.iso8601(iso.to_s) >= cutoff
+    rescue ArgumentError
+      false
+    end
+
+    def print_counts(counts, days)
+      @stdout.puts("chi context report: the last #{days} day#{"s" unless days == 1}, #{counts[:sessions]} session" \
+                   "#{"s" unless counts[:sessions] == 1} (mode #{Config.get("context.candidates.mode")})")
+      @stdout.puts("  candidates: proposed #{counts[:proposed]} · mentioned #{counts[:mentioned]} · " \
+                   "attached by you #{counts[:attached]} · declined #{counts[:declined]} · " \
+                   "detached #{counts[:detached]} · withdrawn #{counts[:withdrawn]}")
+      @stdout.puts("  on mode: judge attached #{counts[:judge_attached]} · you removed #{counts[:judge_removed]} of them " \
+                   "later · carded #{counts[:carded]} · /context attach #{counts[:command_attached]} · " \
+                   "/context decline #{counts[:command_declined]} (the card's buttons)")
+      @stdout.puts("  judge: #{counts[:asks]} asks · judged #{counts[:stated]} · no task yet #{counts[:unstated]} · " \
+                   "#{counts[:candidates_judged]} candidates judged")
+      return if counts[:candidates_judged].zero?
+
+      @stdout.puts("  would attach (each candidate's latest judged ask):")
+      counts[:would].each do |threshold, count|
+        mark = { counts[:threshold] => "  threshold", counts[:offer_threshold] => "  offer_threshold" }[threshold]
+        @stdout.puts(format("    ≥ %.1f  %d%s", threshold, count, mark))
+      end
+      agreement = counts[:agreement]
+      @stdout.puts("  against your own choice (#{agreement[:candidates]} judged candidates you attached, " \
+                   "mentioned or declined), at #{counts[:threshold]}: agree #{agreement[:agree]} · " \
+                   "would attach what you declined #{agreement[:wrong_attach]} · " \
+                   "would miss what you attached #{agreement[:missed]}")
+    end
+  end
+end