samagotchi 0.147.0 → 0.149.0

data/lib/samagotchi/session_chain.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 require "time"
+require_relative "answer_tail"
+require_relative "config"
+require_relative "log"
+require_relative "output_formatter"
 require_relative "session"
+require_relative "session_inbox"
+require_relative "steer"
 require_relative "recap_store"
 
 module Samagotchi
@@ -16,9 +22,16 @@ module Samagotchi
     LAST_PREFIX = "last:"
     # Who the carry note is from (ContextNote's label: "note from session chain").
     NOTE_SOURCE = "session chain"
-    # The most of the previous link's recap the carry note takes; a recap is
-    # a few sentences, this only keeps a runaway one under the note's 16 KiB.
+    # The most of the previous link's recap a note takes; a recap is a few
+    # sentences. Characters, not bytes: #note_text holds the carry note to
+    # SessionInbox::NOTE_MAX_BYTES itself.
     RECAP_CHARS = 8000
+    # The most of the previous link's last answer the carry note takes. A
+    # wrap-up closes on what comes next, so a longer one keeps its end.
+    LAST_ANSWER_CHARS = 4000
+    LAST_ANSWER_HEAD = "\n\nIts last answer:\n"
+    # The "…" that marks a cut, in bytes.
+    CUT_MARK_BYTES = 3
 
     module_function
 
@@ -63,14 +76,79 @@ module Samagotchi
     end
 
     # The context note a new link starts with: which session it continues,
-    # from when, and that session's recap with its time, when it has one.
-    # Never more than the recap: no transcript.
-    # @param previous [Session]
+    # from when, that session's recap with its time, when it has one, and
+    # its last answer (#last_answer; session.carry_last_answer). No other transcript. Never over
+    # SessionInbox::NOTE_MAX_BYTES, whatever the session holds: the inbox
+    # rejects a longer note, and a continue writes it after the archive. The
+    # answer gets what the rest leaves.
+    # @param previous [Session] the answer is read fresh from its file
     # @param recap [Hash, nil] RecapStore.read's
     # @return [String]
-    def note_text(previous, recap:)
+    def note_text(previous, recap:, state_dir:)
       head = "This session continues #{previous.id[0, 8]} (#{clock(previous.created_at) || previous.created_at}), the previous link of its chain."
-      "#{head}#{recap_text(recap)}"
+      text = keep_start("#{head}#{recap_text(recap)}", SessionInbox::NOTE_MAX_BYTES)
+      room = SessionInbox::NOTE_MAX_BYTES - text.bytesize - LAST_ANSWER_HEAD.bytesize
+      answer = carried_answer(previous, room: room, state_dir: state_dir)
+      answer ? "#{text}#{LAST_ANSWER_HEAD}#{answer}" : text
+    end
+
+    # The last answer as the carry note takes it, in at most +room+ bytes;
+    # nil with session.carry_last_answer off, when there is none, when a
+    # review link has it (a continue copies review: but not the grants, so
+    # the next link's participants could differ) or when the session can't
+    # be read: this runs inside a continue's rollback, and a note without it
+    # is still a good note.
+    # @return [String, nil]
+    def carried_answer(previous, room:, state_dir:)
+      return nil if previous.review? || !Config.get("session.carry_last_answer")
+
+      text = last_answer(Session.load(previous.id, state_dir: state_dir).messages)
+      text && keep_end(text, room)
+    rescue StandardError => e
+      Log.warn(:worker, "continue_last_answer_failed", sid: previous.id, error: e.class.name, msg: e.message)
+      nil
+    end
+
+    # The session's last word: the text of AnswerTail's newest bubble, with
+    # the wire-format markup stripped, unless that bubble is a step of a
+    # turn (it asked for tools) or old text a later turn never replaced
+    # (one that failed or was cut before it answered). A cut reply keeps
+    # its "[interrupted]": that is what happened.
+    # @param messages [Array<Hash>]
+    # @return [String, nil]
+    def last_answer(messages)
+      found = AnswerTail.find(messages)
+      return nil unless found && found[:content].is_a?(String) && Array(found[:tool_calls]).empty?
+
+      at = messages.rindex { |m| m.equal?(found) }
+      return nil if messages[(at + 1)..].any? { |m| m[:role].to_s == "tool_response" || later_turn?(m) }
+
+      OutputFormatter.strip_markup(found[:content].scrub)
+    end
+
+    # A turn's opening, not a `!shell` line: a command the user ran after
+    # the answer leaves it the last word.
+    def later_turn?(message)
+      Steer.turn_prompt?(message) && !shell_line?(message)
+    end
+
+    # At most +max+ bytes of +text+'s start, cut on a character.
+    def keep_start(text, max)
+      return text if text.bytesize <= max
+
+      "#{text.byteslice(0, max - CUT_MARK_BYTES).scrub("")}…"
+    end
+
+    # +text+'s end: at most LAST_ANSWER_CHARS characters and +max+ bytes,
+    # with the "…" of a cut; nil when no character fits.
+    def keep_end(text, max)
+      return nil if max <= CUT_MARK_BYTES
+
+      text = "…#{text[(1 - LAST_ANSWER_CHARS)..]}" if text.length > LAST_ANSWER_CHARS
+      return text if text.bytesize <= max
+
+      kept = text.byteslice(-(max - CUT_MARK_BYTES), max - CUT_MARK_BYTES).scrub("")
+      kept.empty? ? nil : "…#{kept}"
     end
 
     # +recap+ as a note's tail: " Its recap, as of <time>:\n<text>" (cut
@@ -103,13 +181,18 @@ module Samagotchi
 
         text = msg[:content]
         next unless text.is_a?(String) && !text.strip.empty?
-        next if msg[:turn_id].nil? && text.start_with?("!(")
+        next if shell_line?(msg)
 
         return text.strip
       end
       nil
     end
 
+    # A stored `!shell` line: "!(cmd)\n<output>", no turn_id.
+    def shell_line?(message)
+      message[:turn_id].nil? && message[:content].is_a?(String) && message[:content].start_with?("!(")
+    end
+
     def clock(iso)
       iso && Time.iso8601(iso.to_s).localtime.strftime("%Y-%m-%d %H:%M")
     rescue ArgumentError

data/lib/samagotchi/session_commands.rb

@@ -27,6 +27,10 @@ require_relative "system_one/approval_label"
 require_relative "system_one/record"
 
 module Samagotchi
+  # Loaded on first use (a /objectives line): keeps the bundle test kit's
+  # load budget (spec/samagotchi/testing/sandbox_spec.rb).
+  autoload :ObjectivesCommand, File.expand_path("objectives_command", __dir__)
+
   # The session commands a REPL and a session worker both run: /model,
   # /models, /llm-context, /guardrails, /context, !rollback, !cmd and the answer to a continue offer. They act on
   # the Engine and its TurnFlow; the host prints the result's output and
@@ -50,6 +54,8 @@ module Samagotchi
     REASONING_HISTORY_COMMAND = ReasoningHistoryCommand::NAME
     WORKING_SET_COMMAND = WorkingSetCommand::NAME
     RECAP_COMMAND = RecapCommand::NAME
+    # A literal: ObjectivesCommand loads on first use (the autoload above).
+    OBJECTIVES_COMMAND = "/objectives"
     # A remote catalog has hundreds of ids (OpenRouter ~380): plain /models
     # shows this many per host; /models <text> lists every match.
     MODELS_PER_HOST = 20
@@ -134,6 +140,9 @@ module Samagotchi
       # Only a name: renaming a running session doesn't wait for its turn.
       registry.register(TITLE_COMMAND, "show or set this session's title (--clear: back to its first message)",
                         id: :title, anytime: true, match: ->(text) { text.match?(%r{\A/title(?:\s+.*)?\z}) }) { |text| title(text) }
+      # An edit only writes a note file (it goes in between turns): mid-turn too.
+      registry.register(OBJECTIVES_COMMAND, "show or edit what this session is to achieve (set A | B, add TEXT, edit ID TEXT, done ID…, drop ID…, undo ID…, check ID)",
+                        id: :objectives, anytime: true) { |text| objectives(text) }
       registry.register(HELP_COMMAND, "list the commands, the bundles' too", anytime: true) { |_text| reply(help_listing) }
       registry.register("/stats", "show the session's stats", local: true)
       # /recap with words (on|off|default, or a slip: the usage) runs here:
@@ -534,7 +543,7 @@ module Samagotchi
         rules.each do |rule|
           summary = SystemOne::Record.new(entries, rule: rule).summary
           counts = summary.reject { |key, _| key == :rule }.map { |key, value| "#{key}=#{value}" }.join(", ")
-          lines << "    #{rule}: #{counts}"
+          lines << "    #{rule}#{" (per repo)" if SystemOne::Record.per_repo?(rule)}: #{counts}"
         end
       end
     end
@@ -703,6 +712,12 @@ module Samagotchi
       reply(output, status: status, changed: changed ? [:title] : [])
     end
 
+    # /objectives (ObjectivesCommand): nothing to save, an edit is a note file.
+    def objectives(text)
+      output, status = ObjectivesCommand.new(engine: @engine).run(text.delete_prefix(OBJECTIVES_COMMAND))
+      reply(output, status: status)
+    end
+
     # /recap on|off|default (RecapCommand); :recap in changed when this
     # session's own recap.enabled moved. It doesn't save: its host does on
     # a changed result (Worker#run_command, the REPL).

data/lib/samagotchi/session_continue.rb

@@ -5,6 +5,7 @@ require_relative "session"
 require_relative "session_setup"
 require_relative "session_inbox"
 require_relative "session_chain"
+require_relative "objectives"
 require_relative "child_move"
 require_relative "context_move"
 require_relative "archive_store"
@@ -69,7 +70,8 @@ module Samagotchi
     # +id_or_ref+ (Session#continues) in its folder, on its model (the name
     # it was typed as, so an alias holds) and with its own setup (SessionSetup),
     # starting with a context note from chi: the link and the previous
-    # link's recap (SessionChain.note_text). +model+, when given, is the
+    # link's recap and last answer (SessionChain.note_text), read after the
+    # recap wait, so a turn that finished in it counts. +model+, when given, is the
     # new link's model instead; an inherited one whose host can't run it any
     # more (gone, disabled, an alias naming another host) falls back to the
     # default with a warning (#model_for). The previous link is archived
@@ -208,11 +210,13 @@ module Samagotchi
         ChildMove.apply(move, from: previous.id, to: link.id, state_dir: state_dir)
         # Its movable context too, with a note saying what moved and stayed.
         moved_context = ContextMove.call(from: previous.id, to: link.id, mode: :continue, state_dir: state_dir)
+        # Its objectives last: the list reads as the latest word.
+        Objectives.carry(previous, to: link.id, state_dir: state_dir)
       end
       link = SessionManager.spawn_session(
         prompt: start, preview: preview, title: previous.title, working_directory: previous.working_directory,
         model_name: choice.model, setup: SessionSetup.of(previous), review: previous.review,
-        continues: previous.id, note: SessionChain.note_text(previous, recap: recap),
+        continues: previous.id, note: SessionChain.note_text(previous, recap: recap, state_dir: state_dir),
         note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn
       )
       link.moved_children = move

data/lib/samagotchi/session_inbox.rb

@@ -5,6 +5,7 @@ require "json"
 require "time"
 require "securerandom"
 require_relative "atomic_file"
+require_relative "context_note"
 require_relative "delivery"
 require_relative "log"
 require_relative "session"
@@ -83,11 +84,13 @@ module Samagotchi
     # to the conversation between turns. It never starts a turn.
     # @param source [String] where it came from ("cli", "slack", "session")
     # @param from_session [String, nil] the sending session, for a peer's note
+    # @param objectives [Hash, nil] an objectives note's payload
+    #   (Objectives::List#to_payload)
     # @param now [Time] the time the file is named and stamped by (a spec's clock)
     # @return [String] the note file's path
     # @raise [NoteRejected] for an empty note or one over 16 KiB (never cut)
     def self.write_note(session_id, text:, source: "cli", from_session: nil, from_cwd: nil, state_dir: nil,
-                        now: Time.now)
+                        objectives: nil, now: Time.now)
       body = checked_text(text)
       sd = state_dir || Session.default_state_dir
       notes_dir = File.join(Session.session_dir(session_id, state_dir: sd), NOTES_DIR)
@@ -98,7 +101,7 @@ module Samagotchi
       name = "#{now.strftime("%Y%m%d%H%M%S%9N")}-#{SecureRandom.hex(3)}.json"
       path = File.join(notes_dir, name)
       record = { "text" => body, "source" => source.to_s, "from_session" => from_session,
-                 "from_cwd" => from_cwd, "created_at" => now.iso8601 }.compact
+                 "from_cwd" => from_cwd, "created_at" => now.iso8601, "objectives" => objectives }.compact
       AtomicFile.write(path, JSON.generate(record))
       path
     end
@@ -134,15 +137,20 @@ module Samagotchi
     end
 
     # @return [Hash, nil] {note_id:, text:, source:, from_session:, from_cwd:,
-    #   created_at:}, or nil for a file that holds no usable note
+    #   created_at:}, with an objectives note's objectives: and its header:
+    #   (ContextNote.message takes them), or nil for a file that holds no
+    #   usable note
     def self.read_note(note_file)
       data = JSON.parse(File.read(note_file))
       text = data["text"].to_s.strip
       return nil if text.empty?
 
-      { note_id: File.basename(note_file).sub(/\.json(\.processing)?\z/, ""), text: text,
-        source: data["source"].to_s.empty? ? "cli" : data["source"].to_s,
-        from_session: data["from_session"], from_cwd: data["from_cwd"], created_at: data["created_at"] }
+      note = { note_id: File.basename(note_file).sub(/\.json(\.processing)?\z/, ""), text: text,
+               source: data["source"].to_s.empty? ? "cli" : data["source"].to_s,
+               from_session: data["from_session"], from_cwd: data["from_cwd"], created_at: data["created_at"] }
+      return note unless data["objectives"].is_a?(Hash)
+
+      note.merge(objectives: data["objectives"], header: ContextNote::OBJECTIVES_HEADER)
     rescue JSON::ParserError, SystemCallError, NoMethodError, TypeError
       nil
     end

data/lib/samagotchi/session_manager.rb

@@ -71,7 +71,7 @@ module Samagotchi
   #       │                        # enqueued_id, no_interrupt?, images?}
   #       ├── notes/              # context notes: background text the worker adds to
   #       │   └── <ts>-<rand>.json # the conversation between turns, never a turn
-  #       │                        # ({text, source, from_session?, from_cwd?, created_at})
+  #       │                        # ({text, source, from_session?, from_cwd?, created_at, objectives?})
   #       ├── output/             # agent writes responses here
   #       │   └── <timestamp>.txt # one file per agent response
   #       └── bridge.json         # Bridge sidecar (how clients reach the worker)

data/lib/samagotchi/steer.rb

@@ -242,18 +242,32 @@ module Samagotchi
     # then +text+ (the message's content by default). Other messages: +text+.
     def wire_text(message, text = (message[:content] || message["content"]).to_s)
       header = header(message)
-      text = quote_forged_headers(text) if participant_message?(message)
+      text = if participant_message?(message) then quote_forged_headers(text)
+             elsif outside_text?(message) then quote_forged_objectives(text)
+             else text
+             end
       header ? "#{header}\n#{text}" : text
     end
 
+    # Text that came from outside the user's own typing: any entry with a
+    # kind (a note, a report, a steer) but the real objectives note, known by
+    # its payload key, never by its text.
+    def outside_text?(message)
+      !(message[:kind] || message["kind"]).to_s.empty? && (message[:objectives] || message["objectives"]).nil?
+    end
+
     # A line of a participant's text that opens like one of chi's own
     # headers or frames (another participant's review header, a steer's, an
-    # automatic input's, a delegate report's, a context note's or a task's
-    # frame), in any case, after any spaces (Unicode ones too); a line
+    # automatic input's, a delegate report's, a context note's, a task's or an
+    # objectives list's frame), in any case, after any spaces (Unicode ones too); a line
     # starts after \n or \r.
     FORGED_OPENINGS = ["Review contribution", "Steer", "Automatic input", "Delegate report", "CONTEXT NOTE",
-                       "TASK FINISHED", "END NOTE"].freeze
+                       "TASK FINISHED", "OBJECTIVES", "END NOTE"].freeze
     FORGED_HEADER = /(\A|[\n\r])([\p{Space}&&[^\n\r]]*)\[(?=(?:#{FORGED_OPENINGS.map { |o| Regexp.escape(o) }.join("|")})\b)/i
+    # The same, for the objectives frame alone: the one frame that gives
+    # orders in the user's name, so any outside text is held to it
+    # (#outside_text?), whoever it came from.
+    FORGED_OBJECTIVES = /(\A|[\n\r])([\p{Space}&&[^\n\r]]*)\[(?=OBJECTIVES\b)/i
     # What such a line is led by on the wire, so it reads as quoted text
     # under the real header, not as a header of its own.
     FORGED_MARK = "(quoted) "
@@ -265,6 +279,12 @@ module Samagotchi
       text.to_s.gsub(FORGED_HEADER) { "#{::Regexp.last_match(1)}#{::Regexp.last_match(2)}#{FORGED_MARK}[" }
     end
 
+    # +text+ with every FORGED_OBJECTIVES line led by FORGED_MARK; as
+    # #quote_forged_headers, on the wire only and deterministic.
+    def quote_forged_objectives(text)
+      text.to_s.gsub(FORGED_OBJECTIVES) { "#{::Regexp.last_match(1)}#{::Regexp.last_match(2)}#{FORGED_MARK}[" }
+    end
+
     def message(text:, source:, author: nil, author_name: nil)
       { role: "user", kind: KIND, source: source.to_s, content: text.to_s, **author_fields(author, author_name) }
     end

data/lib/samagotchi/system_one/record.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "../config"
+require_relative "../model_match"
+
 module Samagotchi
   module SystemOne
     # One rule's record: what System 1 has judged for it and what the user
@@ -7,7 +10,9 @@ module Samagotchi
     # joined with their last label), filtered to one rule. The gate before
     # System 1 answers for the user: enough clean allows at the threshold,
     # and no false allow among the rule's last 20 labelled asks
-    # (docs/guardrails.md, "System 1").
+    # (docs/guardrails.md, "System 1"). A rule in
+    # guardrails.system_one.repo_rules goes by repository: what the user allowed
+    # in one says nothing about another, so its record is built per repo.
     #
     # An ask with no label, no probability, or a `none` label counts for
     # neither side: only a judgment the user actually answered teaches
@@ -21,13 +26,22 @@ module Samagotchi
       # How many of the rule's labelled asks the false-allow check looks at.
       WINDOW = 20
 
+      # Whether +rule+'s record goes by repository
+      # (guardrails.system_one.repo_rules, read like .rules).
+      def self.per_repo?(rule)
+        ModelMatch.parse(Config.get("guardrails.system_one.repo_rules")).include?(rule.to_s)
+      end
+
       attr_reader :rule, :entries
 
       # @param entries [Array<Hash>] SystemOne::Log#entries, oldest first
       # @param rule [String] the rule the record is for
-      def initialize(entries, rule:)
+      # @param repo [String, nil] only this repository's asks (a judgment's
+      #   repo: Guardrails::Targets#repo, its common git dir); nil: all of the
+      #   rule's. A line with no repo is in no repository's record.
+      def initialize(entries, rule:, repo: nil)
         @rule = rule.to_s
-        @entries = Array(entries).select { |entry| entry["rule"].to_s == @rule }
+        @entries = Array(entries).select { |entry| entry["rule"].to_s == @rule && (repo.nil? || entry["repo"] == repo) }
       end
 
       # @param threshold [Float] the probability an auto-allow needs

data/lib/samagotchi/testing/boundary.rb

@@ -43,6 +43,7 @@ module Samagotchi
         Allowed.new(name: "Samagotchi::Log.debug", file: "samagotchi/log"),
         Allowed.new(name: "Samagotchi::Config.get", file: "samagotchi/config"),
         Allowed.new(name: "Samagotchi::VERSION", file: "samagotchi/version"),
+        Allowed.new(name: "Samagotchi::CancellationController", file: "samagotchi/cancellation_controller"),
         # The kit itself, for a bundle's own specs.
         Allowed.new(name: "Samagotchi::Testing", file: "samagotchi/testing")
       ].freeze

data/lib/samagotchi/testing/host.rb

@@ -39,6 +39,7 @@ module Samagotchi
           notify: ->(text, level, label, fallback_for: nil) { recorder.notify(text, level, label, fallback_for) },
           ask_user: ->(question) { recorder.ask_user(question) },
           cancelled: -> { recorder[:cancelled] },
+          turn_running: -> { recorder[:running] },
           card: ->(**card) { recorder.card(**card) },
           ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil|
             recorder.ask_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,

data/lib/samagotchi/tool_activity.rb

@@ -23,6 +23,7 @@ require_relative "tools/context_read"
 require_relative "tools/delegate"
 require_relative "tools/delegate_result"
 require_relative "tools/forget_outputs"
+require_relative "tools/objectives_tool"
 
 module Samagotchi
   # The one-line summary of a tool call that the UIs show ("reading file",
@@ -85,6 +86,15 @@ module Samagotchi
       event
     end
 
+    def objectives_proposal?(call) = call[:action].to_s.strip.downcase == Tools::ObjectivesTool::PROPOSE
+
+    # An objectives row's words: "O2 note · evidence", or "propose done O2 note".
+    def objectives_title(call)
+      return "#{Tools::ObjectivesTool::PROPOSE} #{call[:change]} #{call[:id]} #{call[:text]} · #{call[:note]}".squeeze(" ") if objectives_proposal?(call)
+
+      "#{call[:id]} #{call[:note]}#{" · #{call[:evidence]}" unless call[:evidence].to_s.strip.empty?}"
+    end
+
     # An execute's description, cut as a row's title; nil for the rest.
     def command_description(tool_name, call)
       return nil unless call.is_a?(Hash) && ToolView::TOOLS.include?(tool_name)
@@ -112,6 +122,7 @@ module Samagotchi
              when Tools::Read::NAME, Tools::MemoryRead::NAME then call[:content]
              when Tools::Write::NAME, Tools::Edit::NAME, Tools::MemoryWrite::NAME then call[:path]
              when Tools::Execute::NAME, Tools::TaskCreate::NAME then command_title(call[:content])
+             when Tools::ObjectivesTool::NAME then objectives_title(call)
              end
       text = text.to_s.strip
       return nil if text.empty?
@@ -205,6 +216,7 @@ module Samagotchi
       when Tools::Delegate::NAME then "delegating"
       when Tools::DelegateResult::NAME then "waiting for a delegate"
       when Tools::ForgetOutputs::NAME then forget_outputs_action(call)
+      when Tools::ObjectivesTool::NAME then objectives_proposal?(call) ? "proposing a change" : "recording a move"
       else registry_entry(registry, tool_name)&.label || "calling tool"
       end
     end
@@ -430,6 +442,11 @@ module Samagotchi
         parts << "restore=#{preview_tool_param(request.restore.join(","))}" if request.restore?
         parts << "note=#{preview_tool_param(request.note)}" unless request.note.empty?
         parts.empty? ? nil : parts.join(" ")
+      when Tools::ObjectivesTool::NAME
+        parts = ["id=#{preview_tool_param(call[:id])}", "note=#{preview_tool_param(call[:note])}"]
+        parts.unshift("change=#{preview_tool_param(call[:change])}") if objectives_proposal?(call)
+        parts << "evidence=#{preview_tool_param(call[:evidence])}" unless call[:evidence].to_s.strip.empty?
+        parts.join(" ")
       when Tools::AskUserQuestion::NAME
         parts = ["question=#{preview_tool_param(call[:question] || call[:content])}"]
         opts = call[:options]

data/lib/samagotchi/tool_declarations.rb

@@ -440,6 +440,40 @@ module Samagotchi
           },
           required: %w[question options]
         }
+      },
+      {
+        name: "objectives",
+        description: "Record a move on one of the objectives in the OBJECTIVES note: in a line, what you did or found that moves it, so the user can follow. One when an objective really moved, not per step. Or propose a change to the list (action propose): the user sees a card and applies it or not. This tool doesn't edit the list, change a status or mark anything done, and it approves nothing; the user edits the list with /objectives. Asked to change it, propose it or say so, instead of saying you changed it.",
+        parameters: {
+          type: "object",
+          properties: {
+            action: {
+              type: "string",
+              description: "move or propose"
+            },
+            id: {
+              type: "string",
+              description: "The objective's id, e.g. O2 (not for a proposed add)"
+            },
+            note: {
+              type: "string",
+              description: "A move: what moved, in a line. A proposal: why, in a line"
+            },
+            evidence: {
+              type: "string",
+              description: "Optional, a move's: what shows it (a commit, a test count, a file)"
+            },
+            change: {
+              type: "string",
+              description: "A proposal's: add, reword, done or drop"
+            },
+            text: {
+              type: "string",
+              description: "A proposed add's or reword's new text"
+            }
+          },
+          required: %w[action note]
+        }
       }
     ].freeze
 

data/lib/samagotchi/tools/builtin_calls.rb

@@ -53,7 +53,8 @@ module Samagotchi
         "delegate" => { content: "task", fallback: :prefix_or_raw },
         "ask_user_question" => { content: "question", also: %w[question], verbatim: %w[options], options: true,
                                  fallback: :raw },
-        "forget_outputs" => { content: "note", also: %w[note], verbatim: %w[ids keep restore] }
+        "forget_outputs" => { content: "note", also: %w[note], verbatim: %w[ids keep restore] },
+        "objectives" => { content: "note", also: %w[note] }
       }.freeze
 
       # A name the model uses for a built-in, mapped to that built-in (a model

data/lib/samagotchi/tools/builtins.rb

@@ -25,6 +25,7 @@ require_relative "delegate"
 require_relative "delegate_result"
 require_relative "ask_user_question"
 require_relative "forget_outputs"
+require_relative "objectives_tool"
 require_relative "../guardrails/parent_approvals"
 require_relative "../guardrails/pair_boundary"
 require_relative "../model_profile"
@@ -58,7 +59,8 @@ module Samagotchi
         ContextRead,
         Delegate,
         DelegateResult,
-        AskUserQuestion
+        AskUserQuestion,
+        ObjectivesTool
       ].freeze
       # The built-ins an LLM context layer adds (offered only under it).
       LAYER_CLASSES = [ForgetOutputs].freeze
@@ -115,6 +117,7 @@ module Samagotchi
           DelegateResult.call(call[:content], session: call[:session], timeout: call[:timeout], peers: kctx.peers)
         end,
         AskUserQuestion::NAME => ->(call, kctx) { kctx.ask_user_question(call) },
+        ObjectivesTool::NAME => ->(call, kctx) { ObjectivesTool.call(call, peers: kctx.peers) },
         ForgetOutputs::NAME => ->(call, kctx) { kctx.forget_outputs(call) }
       }.freeze
 

data/lib/samagotchi/tools/objectives_tool.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "../tool_response"
+
+module Samagotchi
+  # Read at a call only: the builtins' file list loads this, Session not with it.
+  autoload :Objectives, File.expand_path("../objectives", __dir__)
+
+  module Tools
+    # The objectives tool's two actions. A move: what the model did or found for
+    # an objective. Information only: it never changes a status or the list
+    # (the user does, /objectives), and nothing is written here: the call in
+    # history is the record, which Objectives.build reads back. A proposal: a
+    # change to the list the user applies from a card with one tap, the card's
+    # action being the /objectives line; the model never changes the list by
+    # itself. See docs/internals/objectives.md.
+    class ObjectivesTool
+      NAME = "objectives"
+      MOVE = "move"
+      PROPOSE = "propose"
+      PROPOSED = "Proposed %s. The list is unchanged: the user sees a card and applies it or not."
+      RECORDED = "Recorded a move on %s."
+      EDITED_BY_USER = "The user edits the list with /objectives."
+      NONE = "There are no objectives here, so nothing was recorded. #{EDITED_BY_USER}".freeze
+
+      def self.name = NAME
+
+      # Whether +output+, a saved run, is this tool's answer that it recorded a
+      # move on +id+ (Objectives.moves_in). Positive: a run that recorded
+      # nothing (no list, a refusal, a denial, an interrupt) has no such answer.
+      def self.recorded?(output, id)
+        output.to_s.sub(ToolResponse::LEAD, "").start_with?(RECORDED % id)
+      end
+
+      # @param call [Hash] the internal call (BuiltinCalls: action:, id:,
+      #   note:, evidence:)
+      # @param peers [#objectives, nil] the session's list
+      # @return [String] the tool result
+      def self.call(call, peers:)
+        action = call[:action].to_s.strip.downcase
+        unless action.empty? || [MOVE, PROPOSE].include?(action)
+          return "Error: this tool records a move (action: move) or proposes a change (action: propose); it edits nothing. #{EDITED_BY_USER}"
+        end
+
+        list = peers&.objectives
+        return NONE if list.nil? || list.empty?
+        return propose(list, call, peers) if action == PROPOSE
+
+        id = Objectives.move_id(call)
+        refusal(list, id, call) || "#{RECORDED % id} The list is unchanged: this tool doesn't edit it. #{EDITED_BY_USER}"
+      end
+
+      def self.propose(list, call, peers)
+        proposal = Objectives::Proposal.against(list, change: call[:change].to_s.strip.downcase, id: Objectives.move_id(call),
+                                                      text: Objectives.clean(call[:text]), note: Objectives.clean(call[:note]))
+        refused = proposal.refusal(list)
+        return "Error: #{refused}. Nothing was proposed." if refused
+
+        return "Error: at most #{Objectives::PROPOSALS_PER_TURN} proposals a turn. Nothing more was proposed." unless peers.propose_objective(proposal)
+
+        format(PROPOSED, proposal.line.delete_prefix("/objectives "))
+      end
+      private_class_method :propose
+
+      def self.refusal(list, id, call)
+        item = list.find(id)
+        return "Error: no objective #{id} (this session's: #{list.items.map(&:id).join(", ")}). Nothing was recorded." unless item
+        return "Error: #{id} was dropped, so nothing was recorded." if item.status == Objectives::DROPPED
+
+        "Error: a move needs a note: what moved, in a line." if Objectives.clean(call[:note]).empty?
+      end
+      private_class_method :refusal
+    end
+  end
+end

data/lib/samagotchi/tools/peers.rb

@@ -27,6 +27,9 @@ module Samagotchi
       # A person's message waits for the turn's next boundary: never here
       # (Engine::PeerView asks the running turn).
       def input_waiting? = false
+
+      # The session's objectives: none here (Engine::PeerView reads them).
+      def objectives = nil
     end
   end
 end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.147.0"
+  VERSION = "0.149.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end