samagotchi 0.147.0 → 0.149.0

data/lib/samagotchi/objectives.rb

@@ -0,0 +1,395 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+
+require_relative "atomic_file"
+require_relative "context_note"
+require_relative "llm_context_stale"
+require_relative "log"
+require_relative "message_time"
+require_relative "objectives_check"
+require_relative "session"
+require_relative "session_chain"
+require_relative "session_inbox"
+require_relative "tools/objectives_tool"
+
+module Samagotchi
+  # A session's objectives: what the user wants it to achieve, a list they
+  # type (/objectives, ObjectivesCommand). The list lives in the conversation
+  # as a note entry (ContextNote::OBJECTIVES_HEADER, its payload under the
+  # message's :objectives), each edit a whole new list that replaces the one
+  # before it. Pure but for the file reads named below, built from a
+  # conversation as WorkingSet is. The model's moves are its calls of the
+  # objectives tool (Tools::ObjectivesTool), read back from the same
+  # conversation: not entries. See docs/internals/objectives.md.
+  module Objectives
+    # Who a list's note is from (ContextNote's label).
+    SOURCE = "objectives"
+    ACTIVE = "active"
+    DONE = "done"
+    DROPPED = "dropped"
+    STATUSES = [ACTIVE, DONE, DROPPED].freeze
+    ID = /\AO(\d+)\z/
+    # What a list with nothing left to send says, so that it still replaces
+    # the one before it.
+    NONE_LEFT = "(no objectives now)"
+    # Cards a turn may leave: a model's proposals are for reading.
+    PROPOSALS_PER_TURN = 3
+    # Notes that say nothing new from outside: the list's own, and a continue's
+    # carry note, which holds the agent's last answer (#outside_note?).
+    NOT_OUTSIDE = [SOURCE, SessionChain::NOTE_SOURCE].freeze
+    # Beside the session's notes/: what #with_lock takes.
+    LOCK_FILE = "objectives.lock"
+    # Proposal cards answered, {card id => APPLIED | DISMISSED}, so that a repeat
+    # of a card's line can't apply again. Under #with_lock.
+    CARDS_FILE = "objectives_cards.json"
+    APPLIED = "applied"
+    DISMISSED = "dismissed"
+    # A text's own done-when: the last group, an earlier one stays text.
+    DONE_WHEN = /\A(.*)\(done when:\s*(.*?)\s*\)\z/i
+
+    # One objective: +id+ "O1", never reused; +status+ ACTIVE, DONE or
+    # DROPPED; +done_when+ an optional hint, never enforced.
+    Item = Data.define(:id, :text, :status, :done_when) do
+      def initialize(id:, text:, status: ACTIVE, done_when: nil)
+        super
+      end
+
+      # The line the frame and /objectives show.
+      def line
+        mark = status == ACTIVE ? "" : "[#{status}] "
+        "#{id} #{mark}#{text}#{" (done when: #{done_when})" if done_when}"
+      end
+
+      def to_payload = { "id" => id, "text" => text, "status" => status, "done_when" => done_when }.compact
+    end
+
+    # What the model last said moved an objective: information only, read
+    # from its tool call, and shown by /objectives.
+    # +ref+ names the call itself, words apart: its run's id and its model
+    # entry's time, so a later move in the same words is another move, and so is
+    # one after a rollback hands the same id out again.
+    Move = Data.define(:id, :note, :evidence, :ref) do
+      def initialize(id:, note:, evidence:, ref: nil) = super
+
+      def line = evidence.empty? ? note : "#{note} (evidence: #{evidence})"
+    end
+
+    # What the user did to one objective between two lists, for the entry's
+    # line: +kind+ added, done, dropped, reopened or reworded; +was+ a
+    # reworded one's old text. Display only, computed from the two lists.
+    Change = Data.define(:id, :kind, :text, :was) do
+      def to_h = { id: id, kind: kind, text: text, was: was }.compact
+    end
+
+    # A change the model proposes (the objectives tool), shown to the user as a
+    # card whose action is #line: the same edit they could type. +change+ add,
+    # reword, done or drop; +note+ why.
+    Proposal = Data.define(:change, :id, :text, :note, :was) do
+      # +was+: what a reword was proposed against (Objectives.fingerprint).
+      def initialize(change:, id:, text:, note:, was: nil)
+        super
+      end
+
+      # A proposal against +list+: a reword keeps the item's done-when unless its
+      # text brings one, and carries what it was proposed against.
+      def self.against(list, change:, id:, text:, note:)
+        item = change == "reword" ? list.find(id) : nil
+        return new(change: change, id: id, text: text, note: note) unless item
+
+        kept = item.done_when && !text.empty? && !text.match?(DONE_WHEN) ? "#{text} (done when: #{item.done_when})" : text
+        new(change: change, id: id, text: kept, note: note, was: Objectives.fingerprint(item))
+      end
+
+      # What's wrong with it against +list+, nil when it can apply.
+      def refusal(list)
+        return "change must be add, reword, done or drop" unless %w[add reword done drop].include?(change)
+        return "#{change} needs a text" if %w[add reword].include?(change) && text.empty?
+        return nil if change == "add"
+
+        list.find(id) ? nil : "no objective #{id} (this session's: #{list.items.map(&:id).join(", ")})"
+      end
+
+      # The /objectives line that applies it. An add's text can't split in two.
+      def line
+        case change
+        when "add" then "/objectives add #{text.gsub(/(?<!\S)\|(?!\S)/, "/")}"
+        when "reword" then "/objectives edit #{id} #{text}"
+        else "/objectives #{change} #{id}"
+        end
+      end
+
+      # The card's Apply: #line behind the prefix ObjectivesCommand reads.
+      def action_line(card)
+        line.sub("/objectives ", "/objectives --card #{card} #{"--was #{was} " if was}")
+      end
+
+      def title
+        case change
+        when "add" then "Add an objective?"
+        when "reword" then "Reword #{id}?"
+        when "done" then "Mark #{id} done?"
+        else "Drop #{id}?"
+        end
+      end
+
+      # The card's body: what, why, and the line for a terminal, which shows no button.
+      def body = [(text unless text.empty?), (note unless note.empty?), "`#{line}`"].compact.join("\n\n")
+    end
+
+    # The list: its items and the number the next id takes (it only grows,
+    # so a /objectives set doesn't reuse an id it dropped), and +moves+, the
+    # latest Move per id, which #build folds from the tool calls (never in
+    # the frame or the payload). Edits answer a new List.
+    List = Data.define(:items, :next_number, :moves) do
+      def initialize(items: [], next_number: 1, moves: {})
+        super
+      end
+
+      # Nothing was ever set.
+      def empty? = items.empty?
+
+      def find(id) = items.find { |item| item.id == id }
+
+      # @param text [String]
+      # @param done_when [String, nil]
+      # @return [List]
+      def add(text, done_when: nil)
+        with(items: items + [Item.new(id: "O#{next_number}", text: text, done_when: done_when)], next_number: next_number + 1)
+      end
+
+      # A new list in place of this one; the ids go on from this one's.
+      # @param entries [Array<Hash>] {text:, done_when:}
+      # @return [List]
+      def set(entries)
+        entries.reduce(with(items: [])) { |list, entry| list.add(entry[:text], done_when: entry[:done_when]) }
+      end
+
+      # @return [List]
+      def mark(id, status)
+        with(items: items.map { |item| item.id == id ? item.with(status: status) : item })
+      end
+
+      # @return [List]
+      def reword(id, text, done_when: nil)
+        with(items: items.map { |item| item.id == id ? item.with(text: text, done_when: done_when) : item })
+      end
+
+      # The note's text: what the model is shown (a dropped one isn't).
+      def text
+        lines = items.reject { |item| item.status == DROPPED }.map(&:line)
+        lines.empty? ? NONE_LEFT : lines.join("\n")
+      end
+
+      # What the note carries, in one key style: strings, as a save leaves them.
+      def to_payload = { "next" => next_number, "items" => items.map(&:to_payload) }
+
+      # What the page draws: the items, each with its last move and last check,
+      # and whether the newest edit is still a file waiting to go in.
+      # @param checks [Hash{String => Hash}] ObjectivesCheck.view_of's
+      def to_view(pending:, checks: {})
+        { items: items.map { |item| item_view(item, checks[item.id]) }, pending: pending }
+      end
+
+      private
+
+      def item_view(item, check)
+        move = moves[item.id]
+        view = item.to_payload
+        view = view.merge("move" => { "note" => move.note, "evidence" => move.evidence }) if move
+        check ? view.merge("check" => check) : view
+      end
+    end
+
+    module_function
+
+    # One edit's read and write as one step, across threads (each anytime command
+    # has its own) and processes: each note holds a whole list, so two edits that
+    # read the same list would lose one. The worker's absorb holds it too, so an
+    # edit reads neither between the note going into the conversation and its
+    # file going. An edit's events go under it: the order is always this lock,
+    # then the event log. Nothing takes this under the event log.
+    def with_lock(session_dir)
+      FileUtils.mkdir_p(session_dir)
+      File.open(File.join(session_dir, LOCK_FILE), File::RDWR | File::CREAT, 0o600) do |file|
+        file.flock(File::LOCK_EX)
+        yield
+      end
+    end
+
+    # An item's words, short: what a proposed reword was made against.
+    def fingerprint(item) = Digest::SHA256.hexdigest("#{item.text}\0#{item.done_when}")[0, 12]
+
+    # How a proposal card was answered, nil when it wasn't. Under #with_lock.
+    def card_state(session_dir, card)
+      JSON.parse(File.read(File.join(session_dir, CARDS_FILE)))[card]
+    rescue SystemCallError, JSON::ParserError, TypeError
+      nil
+    end
+
+    # Under #with_lock.
+    def record_card(session_dir, card, state)
+      path = File.join(session_dir, CARDS_FILE)
+      known = begin
+        JSON.parse(File.read(path))
+      rescue SystemCallError, JSON::ParserError
+        {}
+      end
+      AtomicFile.write(path, JSON.generate(known.merge(card => state)))
+    end
+
+    # The id a call names, as the list spells it.
+    def move_id(call) = call[:id].to_s.strip.upcase
+
+    # A call's text as one line.
+    def clean(text) = text.to_s.gsub(/[[:space:]]+/, " ").strip
+
+    # The list as +conversation+ leaves it, +pending+ over it: a pending file
+    # is newer than anything the conversation holds. Pure.
+    # @param conversation [Array<Hash>, nil] the stored entries
+    # @param pending [Hash, nil] #pending_payload's
+    # @param running [Array<Hash>, nil] the running turn's conversation, which
+    #   +conversation+ (a session's messages) doesn't hold yet: its moves count
+    # @return [List]
+    def build(conversation, pending: nil, running: nil)
+      conversation = Array(conversation)
+      list = from_payload(pending) || conversation.reduce(List.new) do |so_far, message|
+        (ContextNote.note?(message) && from_payload(ContextNote.fetch(message, :objectives))) || so_far
+      end
+      list.empty? ? list : list.with(moves: moves_in(conversation).merge(moves_in(Array(running))))
+    end
+
+    # The latest Move per id among the conversation's objectives calls that
+    # recorded one (LLMContextStale.paired_runs, as the working set reads its
+    # runs: a call_tool's too, both hosts' forms). Tools::ObjectivesTool
+    # .recorded? is the check: a call with no list, a refused, a denied or an
+    # interrupted one recorded nothing.
+    # @return [Hash{String => Move}]
+    def moves_in(conversation)
+      LLMContextStale.paired_runs(conversation).each_with_object({}) do |run, moves|
+        next unless run.call[:name] == Tools::ObjectivesTool::NAME
+
+        id = move_id(run.call)
+        next unless Tools::ObjectivesTool.recorded?(run.text, id)
+
+        moves[id] = Move.new(id: id, note: clean(run.call[:note]), evidence: clean(run.call[:evidence]), ref: move_ref(conversation, run))
+      end
+    end
+
+    # Whether a note is news from outside the session's own words, for what reads
+    # a conversation as evidence or as incoming (ObjectivesCheck, ObjectivesAudit).
+    # @param source [String, nil] the note's source
+    # @param payload [Object] the note's :objectives
+    def outside_note?(source, payload) = payload.nil? && !NOT_OUTSIDE.include?(source)
+
+    def move_ref(conversation, run)
+      called = conversation[0...run.index].reverse_each.find { |entry| entry[:role].to_s == "model" }
+      "#{run.ref&.id}@#{called && called[MessageTime::KEY]}"
+    end
+    private_class_method :move_ref
+
+    # A session's list now, its unabsorbed newest file included.
+    # @return [List]
+    def current(session_id, conversation, state_dir:, running: nil)
+      build(conversation, pending: pending_payload(Session.session_dir(session_id, state_dir: state_dir)), running: running)
+    end
+
+    # The list as the page draws it (List#to_view), nil with no list: the page
+    # shows nothing then.
+    # @return [Hash, nil]
+    def view(session_id, conversation, state_dir:, running: nil)
+      dir = Session.session_dir(session_id, state_dir: state_dir)
+      pending = pending_payload(dir)
+      list = build(conversation, pending: pending, running: running)
+      list.empty? ? nil : list.to_view(pending: !pending.nil?, checks: ObjectivesCheck.view_of(dir, list))
+    end
+
+    # One note's list for the page's entry: its items and, when there was a
+    # list before it, what changed.
+    # @param payload [Object] the note's :objectives
+    # @param before [List, nil] the list before this note
+    # @return [Hash, nil] nil for what isn't a list
+    def entry(payload, before: nil)
+      list = from_payload(payload) or return nil
+
+      fields = { items: list.items.map(&:to_payload) }
+      fields[:changes] = changes(before, list).map(&:to_h) if before && !before.empty?
+      fields
+    end
+
+    # What the user did between two lists, in the new list's order.
+    # @return [Array<Change>]
+    def changes(before, after)
+      (before.items.map(&:id) | after.items.map(&:id)).filter_map do |id|
+        change_of(before.find(id), after.find(id))
+      end
+    end
+
+    # The newest objectives note waiting in +session_dir+'s notes/.
+    # @return [Hash, nil] its payload
+    def pending_payload(session_dir)
+      SessionInbox.find_new_note_files(session_dir).reverse_each do |file|
+        payload = SessionInbox.read_note(file)&.dig(:objectives)
+        return payload if from_payload(payload)
+      end
+      nil
+    end
+
+    # @param payload [Object] a note's :objectives; either key style reads
+    # @return [List, nil] nil for what isn't a list (+next+ not an Integer,
+    #   +items+ not an Array): it can't wipe the fold or restart the ids
+    def from_payload(payload)
+      return nil unless payload.is_a?(Hash)
+
+      payload = payload.transform_keys(&:to_s)
+      return nil unless payload["next"].is_a?(Integer) && payload["items"].is_a?(Array)
+
+      items = payload["items"].filter_map { |raw| item_of(raw) }
+      highest = items.map { |item| item.id[ID, 1].to_i }.max || 0
+      List.new(items: items, next_number: [payload["next"], highest + 1].max)
+    end
+
+    # A continue's copy: +previous+'s list as a note file in the new link,
+    # read fresh, its unabsorbed newest file included. It runs inside the
+    # continue's rollback, and a link without the list is still a good link:
+    # a failure is logged. Not for a review link, whose next link's
+    # participants could differ (as SessionChain.carried_answer).
+    # @return [String, nil] the note file's path
+    def carry(previous, to:, state_dir:)
+      return nil if previous.review?
+
+      list = current(previous.id, Session.load(previous.id, state_dir: state_dir).messages, state_dir: state_dir)
+      return nil if list.empty?
+
+      SessionInbox.write_note(to, text: list.text, source: SOURCE, objectives: list.to_payload, state_dir: state_dir)
+    rescue StandardError => e
+      Log.warn(:worker, "continue_objectives_failed", sid: previous.id, error: e.class.name, msg: e.message)
+      nil
+    end
+
+    def change_of(was, now)
+      return Change.new(id: was.id, kind: DROPPED, text: was.text, was: nil) unless now
+      return Change.new(id: now.id, kind: "added", text: now.text, was: nil) unless was
+
+      if now.text != was.text || now.done_when != was.done_when
+        Change.new(id: now.id, kind: "reworded", text: now.text, was: was.text)
+      elsif now.status != was.status
+        Change.new(id: now.id, kind: now.status == ACTIVE ? "reopened" : now.status, text: now.text, was: nil)
+      end
+    end
+    private_class_method :change_of
+
+    def item_of(raw)
+      return nil unless raw.is_a?(Hash)
+
+      raw = raw.transform_keys(&:to_s)
+      return nil unless ID.match?(raw["id"].to_s) && !raw["text"].to_s.empty?
+
+      status = STATUSES.include?(raw["status"]) ? raw["status"] : ACTIVE
+      Item.new(id: raw["id"].to_s, text: raw["text"].to_s, status: status, done_when: raw["done_when"]&.to_s)
+    end
+    private_class_method :item_of
+  end
+end

data/lib/samagotchi/objectives_audit.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "context_note"
+require_relative "log"
+require_relative "objectives"
+require_relative "system_one/question"
+
+module Samagotchi
+  # System 1 watching the objectives, in audit: one yes/no per active objective on
+  # what just came in (a user's message, a note) and what just went out (a finished
+  # answer), each saved as a run for `chi judgments`. Nothing acts on it: no card,
+  # no wake, no push, nothing in a prompt. A per-message judge didn't work as a
+  # gate on the pod (AUC .5 to .66), so this only collects: docs/system-one.md.
+  #
+  # Off unless objectives.system_one says audit, a list has an active objective and
+  # System 1 has a host. The asks run on SideJudgments' threads, one in flight per
+  # direction; what comes meanwhile is a saved skip, with no request.
+  class ObjectivesAudit
+    MODE = "audit"
+    INCOMING = "objectives.incoming"
+    OUTGOING = "objectives.outgoing"
+    QUESTION_ID = "affects"
+    # The most objectives one message asks about.
+    MAX_OBJECTIVES = 6
+    # What the state carries of a message: a message's head, an answer's tail.
+    MESSAGE_CHARS = 2000
+    # Narrow triggers: under these there is too little to affect anything.
+    INCOMING_MIN_CHARS = 40
+    OUTGOING_MIN_CHARS = 400
+    COMMAND_LINE = %r{\A\s*[/!]}
+    QUESTIONS = {
+      INCOMING => "A user works with a coding agent session toward the objective in the state. The state's message just " \
+                  "came in, from the user or as a note. Could it change that objective: what it means, whether it still " \
+                  "stands, how it is to be met, or whether it is met?",
+      OUTGOING => "A coding agent works toward the objective in the state. The state's message is the end of its finished " \
+                  "answer. Does it report something that moves that objective on, blocks it, or changes whether it still stands?"
+    }.freeze
+
+    # Whether this use is on: config.yml, read at each ask.
+    def self.on? = Config.get("objectives.system_one").to_s.strip.downcase == MODE
+
+    # @param client_for [#call] (judgment, session) → a recording client, nil with no host or no saving
+    # @param side [SideJudgments]
+    # @param state_dir [#call] → the sessions folder
+    def initialize(client_for:, side:, state_dir:)
+      @client_for = client_for
+      @side = side
+      @state_dir = state_dir
+    end
+
+    # A user's message, at its turn's start: the caller says it is the owner's.
+    def incoming(session, text)
+      guarded do
+        next unless self.class.on? && text.to_s.strip.length >= INCOMING_MIN_CHARS && !text.match?(COMMAND_LINE)
+
+        ask(INCOMING, session, text.to_s.strip[0, MESSAGE_CHARS])
+      end
+    end
+
+    # A note that just went into the conversation.
+    # @param note [Hash] SessionInbox.read_note's
+    def note(session, note)
+      guarded do
+        next unless Objectives.outside_note?(note[:source], note[:objectives])
+
+        incoming(session, note[:text].to_s)
+      end
+    end
+
+    # A finished answer of the owner's turn: the caller says so.
+    def outgoing(session, text)
+      guarded do
+        next unless self.class.on? && text.to_s.strip.length >= OUTGOING_MIN_CHARS
+
+        ask(OUTGOING, session, text.to_s.strip[-MESSAGE_CHARS..] || text.to_s.strip)
+      end
+    end
+
+    private
+
+    def ask(judgment, session, message)
+      return if session.nil? || session.id.nil? || session.scratch || session.review?
+
+      items = Objectives.current(session.id, session.messages, state_dir: @state_dir.call).items
+                        .select { |item| item.status == Objectives::ACTIVE }.first(MAX_OBJECTIVES)
+      return if items.empty?
+
+      client = @client_for.call(judgment, session) or return
+
+      states = items.map { |item| { "objective" => objective_text(item), "message" => message.scrub } }
+      questions = { QUESTION_ID => SystemOne::Question.new(id: QUESTION_ID, type: "noul", instructions: QUESTIONS.fetch(judgment)) }
+      kind = judgment.tr(".", "_").to_sym
+      return states.each { |state| client.skip(state: state, questions: questions, reason: "busy") } if @side.in_flight?(kind)
+
+      @side.start(kind, warn: method(:warned)) do
+        states.each { |state| client.ask(state: state, questions: questions) }
+      end
+    end
+
+    # What the objective says, with no id or status: a judgment's state stays
+    # comparable across sessions.
+    def objective_text(item) = item.done_when ? "#{item.text} (done when: #{item.done_when})" : item.text
+
+    def guarded
+      yield
+    rescue StandardError => e
+      warned(e)
+    end
+
+    def warned(error)
+      Log.warn(:system_one, "objectives_audit_failed", error: error.class.name, msg: error.message.to_s[0, 200])
+    end
+  end
+end