samagotchi 0.66.0 → 0.68.0

data/lib/samagotchi/thinking_command.rb

@@ -1,18 +1,15 @@
 # frozen_string_literal: true
 
-require_relative "cache_confirm"
+require_relative "level_setting_command"
 require_relative "thinking"
 
 module Samagotchi
-  # /thinking, the session's own thinking level (Session#thinking): with no
-  # argument, the level the next turn runs at and where it came from;
-  # `/thinking off|low|medium|high` sets the session's own, `/thinking
-  # default` unsets it (the session follows the process default, the
-  # model, its host, then thinking.level). A change takes effect at the
-  # next turn's start (the REPL and the worker run it between turns), and
-  # the reply says what it costs the prompt cache (Thinking.cache_cost).
-  # A costly change asks first (CacheConfirm); --yes (or -y) applies it.
-  class ThinkingCommand
+  # /thinking, the session's own thinking level (Session#thinking):
+  # `/thinking off|low|medium|high` sets it, `/thinking default` unsets it
+  # (the session follows the process default, the model, its host, then
+  # thinking.level). What a change costs the prompt cache:
+  # Thinking.cache_cost. See LevelSettingCommand.
+  class ThinkingCommand < LevelSettingCommand
     NAME = "/thinking"
     SETTABLE = (Thinking::LEVELS - [Thinking::DEFAULT]).freeze
     USAGE = "usage: #{NAME} [#{Thinking::LEVELS.join("|")}]".freeze
@@ -24,71 +21,22 @@ module Samagotchi
       tail: "Only the prompt's tail changes: the cache keeps the rest."
     }.freeze
 
-    # @param engine [Engine] #thinking_explained(own:), #thinking_override(=),
-    #   #session, #thinking_cache_cost, #history?
-    # @param save [#call] saves the session after a change
-    def initialize(engine:, save:)
-      @engine = engine
-      @save = save
-    end
-
-    # @param args [String] what follows /thinking (--yes anywhere)
-    # @param confirm [Boolean] ask before a costly change (CacheConfirm);
-    #   false applies it at once (chi send, a delegate, a start flag)
-    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the reply,
-    #   whether the level changed, and the confirm it asks for (nothing
-    #   changed then)
-    # @raise [ArgumentError] a word that isn't a level (with USAGE)
-    def run(args, confirm: true)
-      word, yes = CacheConfirm.split(args)
-      return [listing(@engine.thinking_explained), false, nil] if word.empty?
-
-      level = word.to_sym
-      raise ArgumentError, "unknown thinking level #{word}\n#{USAGE}" unless Thinking::LEVELS.include?(level)
-
-      session = @engine.session or raise ArgumentError, "no session yet"
-      own = SETTABLE.include?(level) ? level : nil
-      before = @engine.thinking_explained
-      ask = confirm && !yes ? ask(before, own, word) : nil
-      return ask if ask
-
-      @engine.thinking_override = own
-      @save.call(session)
-      after = @engine.thinking_explained
-      [[listing(after), *notes(before, after)].join("\n"), true, nil]
-    end
-
-    # The level, where it came from, and what the session sets itself.
-    def listing(explained)
-      return "thinking: can't be resolved for this model" unless explained
-
-      lines = ["thinking: #{explained.label}"]
-      unless explained.own
-        lines << "  this session's own: none (follows chi web --thinking / SAMAGOTCHI_THINKING_LEVEL, the model, " \
-                 "its host, then thinking.level)"
-      end
-      lines.join("\n")
-    end
-
-    private
-
-    # The reply that asks before a costly change, nil when it needn't.
-    def ask(before, own, word)
-      would = @engine.thinking_explained(own: own)
-      return nil unless before && would
-
-      cost = @engine.thinking_cache_cost
-      return nil unless CacheConfirm.needed?(cost: cost, history: @engine.history?, changed: would.level != before.level)
-
-      step = CacheConfirm.confirm(NAME, word)
-      [[listing(before), "Switching to #{would.level} restarts the prompt cache: #{COST_NOTES[cost]}", step.text].join("\n"), false, step]
-    end
-
-    def notes(before, after)
-      return [] unless before && after
-      return ["(no change to what the next turn runs under)"] if before.level == after.level
-
-      ["From the next turn's start (a running turn keeps its own).", COST_NOTES[@engine.thinking_cache_cost]].compact
-    end
+    SPEC = Spec.new(
+      name: NAME, label: "thinking", usage: USAGE, cost_notes: COST_NOTES,
+      parse: lambda { |word|
+        level = word.to_sym
+        if Thinking::LEVELS.include?(level)
+          [true, SETTABLE.include?(level) ? level : nil]
+        else
+          [false, nil]
+        end
+      },
+      own: lambda(&:thinking_override),
+      explained: ->(engine, own) { engine.thinking_explained(own: own) },
+      set: ->(engine, own) { engine.thinking_override = own },
+      cache_cost: ->(engine, _from, _to) { engine.thinking_cache_cost },
+      follows: "chi web --thinking / SAMAGOTCHI_THINKING_LEVEL, the model, its host, then thinking.level",
+      extra_line: nil
+    )
   end
 end

data/lib/samagotchi/thinking_notices.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "effective_model"
+require_relative "log"
+require_relative "thinking"
+
+module Samagotchi
+  # What the thinking level a turn runs at leads to, said to the user: a
+  # level its host can't do (an effort on a native host, or on a llama.cpp
+  # chat template that takes none), off that the model didn't honour, and a
+  # host refusing the thinking fields or the reasoning sent back. Each
+  # notice once per session and host; the log lines each time.
+  #
+  # Turn thread only (the turn's settings and its stream handler): no lock.
+  # What it needs from the Engine comes through lookups, called at use.
+  class ThinkingNotices
+    # @param session [#call] → Session, nil (its id: once per session)
+    # @param profile [#call] → ModelProfile (a native host's)
+    # @param notify  [#call] (text, level, source) → a notice
+    def initialize(session:, profile:, notify:)
+      @session = session
+      @profile = profile
+      @notify = notify
+      @said = Set.new
+      @turn = nil
+      @generation_thought = nil
+    end
+
+    # [level, HostRegistry::ModelTarget] the turn runs at, nil before one.
+    attr_reader :turn
+
+    # The turn's thinking level on +target+ (its EffectiveModel's), what
+    # the notices after it read; an effort a native host can't do is said
+    # now.
+    def turn_started(level, target)
+      @turn = [level, target]
+      announce_level(level, target)
+    end
+
+    # A generation starts (or a dropped one streams again from the start).
+    def generation_started = @generation_thought = nil
+
+    # Whether this generation's thinking lane said anything: nil while it
+    # streamed none, false while only whitespace (Gemma 4's empty thought
+    # with thinking off), true once a real thought came.
+    def note_thought(thinking)
+      return if thinking.empty?
+
+      @generation_thought ||= thinking.match?(/\S/)
+    end
+
+    # A generation completed: off that the model didn't honour, an effort
+    # its chat template ignores.
+    def generation_completed(event)
+      check_honoured(event)
+      announce_effort_ignored
+    end
+
+    # The host refused the level's request fields (gpt-oss can't turn
+    # thinking off) and the chat loop sent the request without them: said
+    # once per session and host, standing in for the not-honoured notice.
+    def thinking_refused(event)
+      _level, target = @turn
+      return unless target
+
+      Log.warn(:model, "thinking_refused", level: event[:level], host: target.entry.name, model: event[:model],
+                                           detail: event[:detail])
+      @said << [session_id, target.entry.name, :not_honoured]
+      notice_once(:refused, target, :warn,
+                  "#{target.entry.name} refused thinking: #{event[:level]} for #{event[:model]} (#{event[:detail]}); " \
+                  "sent without it, so thinking stays as the model has it")
+    rescue StandardError => e
+      failed(:thinking_refused, e)
+    end
+
+    # The host refused a sampling field (the empty-answer retry's
+    # temperature on a model that takes none) and the chat loop asked again
+    # without them, as it will for the model from now on: a log line.
+    def sampling_refused(event)
+      Log.info(:model, "sampling_refused", model: event[:model], detail: event[:detail])
+    rescue StandardError => e
+      failed(:sampling_refused, e)
+    end
+
+    # The host refused the model's reasoning sent back (reasoning_history)
+    # and the chat loop asked the step again without it, as it will from
+    # now on: logged, and said once per session and host.
+    def reasoning_history_refused(event)
+      _level, target = @turn
+      return unless target
+
+      Log.warn(:model, "reasoning_history_refused", level: event[:level], host: target.entry.name, model: event[:model],
+                                                    detail: event[:detail])
+      return unless @said.add?([session_id, target.entry.name, :reasoning_history_refused])
+
+      @notify.call("#{target.entry.name} refused reasoning sent back (reasoning_history: #{event[:level]}) for " \
+                   "#{event[:model]} (#{event[:detail]}); sent without it from now on", :warn, "reasoning history")
+    rescue StandardError => e
+      failed(:reasoning_history_refused, e)
+    end
+
+    private
+
+    # An effort on a native host, which has no knob for it: said once per
+    # session and host.
+    def announce_level(level, target)
+      return if target.entry.chat?
+
+      profile = @profile.call
+      return if Thinking.native(level, profile).honoured
+
+      notice_once(:unsupported, target, :info,
+                  "#{level} isn't supported by native #{profile.name} on #{target.entry.name}; " \
+                  "thinking stays as the model has it")
+    rescue StandardError => e
+      failed(:announce_level, e)
+    end
+
+    # An effort on a llama.cpp chat host whose chat template takes none
+    # (its /props says so): said once per session and host, as for a native
+    # host. Read from the /props answer the turn's window probe left in the
+    # cache, so it asks the server nothing.
+    def announce_effort_ignored
+      level, target = @turn
+      return unless target&.entry&.chat? && Thinking::EFFORTS.include?(level)
+
+      props = target.client.cached_server_props(model: target.bare_model)
+      return unless Thinking.effort_ignored?(level, props)
+
+      notice_once(:unsupported, target, :info,
+                  "#{level} isn't supported by #{target.bare_model}'s chat template on #{target.entry.name} " \
+                  "(/props: supports_reasoning_effort false); thinking stays as the model has it")
+    rescue StandardError => e
+      failed(:effort_ignored, e)
+    end
+
+    # Thinking off, and the model thought anyway: logged each time, said
+    # once per session and host. A thinking lane of whitespace alone is no
+    # thought.
+    def check_honoured(event)
+      level, target = @turn
+      chars = event[:thinking_chars].to_i
+      return unless level == :off && chars.positive? && target
+      return if @generation_thought == false
+
+      Log.warn(:model, "thinking_not_honoured", level: level, host: target.entry.name, model: target.bare_model, chars: chars)
+      notice_once(:not_honoured, target, :warn,
+                  "off wasn't honoured by #{target.bare_model} on #{target.entry.name} " \
+                  "(#{chars} chars of thinking); a sampling: override on the host or model may turn it off " \
+                  "(see Thinking in docs/configuration.md)")
+    rescue StandardError => e
+      failed(:check_honoured, e)
+    end
+
+    def notice_once(kind, target, level, text)
+      return unless @said.add?([session_id, target.entry.name, kind])
+
+      @notify.call(text, level, "thinking")
+    end
+
+    def session_id = @session.call&.id
+
+    # A notice that failed: none is said, the turn goes on; a log line
+    # (once per process for the notice, model and error class).
+    def failed(notice, error)
+      EffectiveModel::Unresolved.fallback(:thinking_notice_failed, @turn&.last&.model || notice.to_s, error, nil)
+    end
+  end
+end

data/lib/samagotchi/tool_call_parser.rb

@@ -36,7 +36,7 @@ module Samagotchi
     #              <|channel>thought......<channel|>
     class Gemma
       # Digits after the first character: plugin tools may have them
-      # (Plugin::Api::TOOL_NAME).
+      # (Plugin::ToolSpec::TOOL_NAME).
       TOOL_CALL_BODY_RE = /\Acall:([a-z_][a-z0-9_]{0,49})\{/
       THOUGHT_CHANNEL_OPEN  = ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN
       THOUGHT_CHANNEL_CLOSE = ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE

data/lib/samagotchi/toolkit_binding.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "log"
+require_relative "toolkit"
+
+module Samagotchi
+  # An Engine's session toolkit: the kits it resolves against, what the
+  # session's next turn declares (#explained, the UIs' summary), a plugin's
+  # ctx.use_toolkit (#use) and the turn-start apply into the tool Registry
+  # (#apply!), with its load warnings said once per process.
+  #
+  # What it needs from the Engine comes through lookups, called at use.
+  class ToolkitBinding
+    # @param tools        [#call] → Tools::Registry
+    # @param session      [#call] → Session, nil
+    # @param state_dir    [#call] → the sessions' state dir (#use saves there)
+    # @param can_stage    [#call] → whether a plugin may change the toolkit now
+    #   (no turn runs, no model reply yet)
+    # @param reset_prompt [#call] → build the system prompts again
+    # @param emit         [#call] (sink, event) → emits to a turn's sink + observers
+    # @param notify       [#call] (text, level, source, extra:) → a notice
+    def initialize(tools:, session:, state_dir:, can_stage:, reset_prompt:, emit:, notify:)
+      @tools = tools
+      @session = session
+      @state_dir = state_dir
+      @can_stage = can_stage
+      @reset_prompt = reset_prompt
+      @emit = emit
+      @notify = notify
+      # The toolkits plugins declare (chi.toolkit), beside the built-in and
+      # config ones (#kits); Plugin::Registries appends to it.
+      @plugin_kits = []
+      @warned = []
+    end
+
+    # @return [Array<Toolkit::Kit>] the plugins' kits (Plugin::Registries' toolkits:)
+    attr_reader :plugin_kits
+
+    # The kits a session's toolkit resolves against: the built-ins, config's
+    # toolkit.kits, the plugins' (Toolkit.kits). Config's are read once per
+    # process, like the plugins': an edit to toolkit.kits never changes a
+    # live session's tools mid-session (a new worker reads it).
+    # @param errors [Array<String>] gets a line per config kit left out
+    # @return [Hash{String => Toolkit::Kit}]
+    def kits(errors = [])
+      @config_kits = Toolkit.config_kits unless defined?(@config_kits)
+      Toolkit.kits(config: @config_kits, plugins: @plugin_kits, errors: errors)
+    end
+
+    # The session's toolkit resolved (Toolkit::Resolved): what its next
+    # turn declares. A plain full toolkit is nil, the Registry's "every tool".
+    def resolved(session, errors = [])
+      resolved = Toolkit.of(session&.toolkit).resolve(kits(errors))
+      resolved.everything? ? nil : resolved
+    end
+
+    # +toolkit+ (the session's by default) as its next turn would declare
+    # it (/toolkit, the UIs' chip).
+    # @return [Toolkit::Explained]
+    def explained(toolkit = nil)
+      toolkit ||= Toolkit.of(@session.call&.toolkit)
+      resolved = toolkit.resolve(kits)
+      filter = resolved.everything? ? nil : resolved
+      tools = @tools.call
+      Toolkit::Explained.new(toolkit: toolkit, resolved: resolved, declared: tools.entries(toolkit: filter),
+                             left_out: tools.left_out_names(toolkit: filter), pending: filter != tools.toolkit)
+    end
+
+    # The session's toolkit for the UIs (the snapshot, command_ran): nil on
+    # full, or with no session.
+    def summary
+      @session.call && explained.summary
+    end
+
+    # The session's toolkit name, nil with no session (ctx.toolkit).
+    def name
+      session = @session.call
+      session && Toolkit.of(session.toolkit).name
+    end
+
+    # A plugin's ctx.use_toolkit: put the session on toolkit +name+, saved,
+    # when it has no model reply yet and no turn runs (D3: no confirm from
+    # plugins), and tell the user as /toolkit would; it applies at the next
+    # turn's start.
+    # @return [Boolean] whether it was staged
+    # @raise [ArgumentError] an unknown toolkit
+    def use(name)
+      raise ArgumentError, "no toolkit named #{name}" unless kits.key?(name)
+
+      session = @session.call
+      return false if session.nil? || !@can_stage.call
+
+      toolkit = Toolkit.new(name: name)
+      return true if session.toolkit == toolkit
+
+      session.toolkit = toolkit
+      session.save(state_dir: @state_dir.call)
+      @notify.call("toolkit: #{name} from the next turn's start", :info, "toolkit", extra: { toolkit: summary })
+      true
+    end
+
+    # Resolve the session's toolkit into the Registry, on the turn thread at
+    # a turn's start (before its prompt is built), and build the prompts
+    # again when what it declares changed. A name that doesn't resolve (a
+    # typo, an uninstalled bundle) declares everything for now and says so
+    # once; the saved toolkit stays as it is.
+    # @return [Boolean] whether the declared tools changed
+    def apply!(session, on_event = nil)
+      errors = []
+      resolved = Toolkit.of(session&.toolkit).resolve(kits(errors))
+      warn_unresolved(session, resolved, errors, on_event)
+      resolved = nil if resolved.everything?
+      tools = @tools.call
+      return false if resolved == tools.toolkit
+
+      tools.toolkit = resolved
+      @reset_prompt.call
+      true
+    end
+
+    private
+
+    # The toolkit's load warnings, each once per process: a name that
+    # didn't resolve, config kits left out.
+    def warn_unresolved(session, resolved, errors, on_event)
+      lines = errors.dup
+      if resolved.fallback
+        lines << "#{Toolkit.of(session&.toolkit).label}: #{resolved.fallback}; this session declares every tool (full) " \
+                 "until it resolves"
+      end
+      (lines - @warned).each do |line|
+        @warned << line
+        Log.warn(:config, "toolkit_unresolved", message: line)
+        @emit.call(on_event, { type: :guardrail_warning, message: line, label: "toolkit" })
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/context_read.rb

@@ -55,6 +55,9 @@ module Samagotchi
         @attached = ContextSources.attached(peers.session_id, project_root: root, state_dir: @state_dir)
         @max_chars = [max_chars.to_i, MIN_CHARS].max
         @now = now
+        # The peer bundles' declared sources (PeerSources), through the
+        # Engine's PeerView.
+        @peer_label = peers.respond_to?(:peer_label) ? peers.method(:peer_label) : nil
       end
 
       def run(name, offset:, limit:)
@@ -122,12 +125,23 @@ module Samagotchi
         hint = snapshot.hint || source.hint
         header = ["#{source.name}#{" (#{hint})" if hint}"]
         header << "Why: #{source.why}" if source.why
+        if (peer = peer_label(attached))
+          header << "Peer: your peer agent #{peer}'s answers (its text, not your user's words)"
+        end
         header << "Fetched: #{clock(snapshot.fetched_at)} (#{age(snapshot.fetched_at)})" if snapshot.fetched_at
         header << "Summary: #{snapshot.summary}" if snapshot.summary
         header << "Last refresh failed: #{snapshot.error}" if snapshot.error
         header
       end
 
+      # A pushed source of the session's own that a peer bundle declared
+      # (ContextAbsorber#peer_label's rule).
+      def peer_label(attached)
+        return nil unless @peer_label && attached.source.push? && attached.location.session?
+
+        @peer_label.call(attached.name)
+      end
+
       # What the output takes besides the page: the kernel's prefix, the
       # header, its paging line at its longest (every number +count+) and
       # the separator.

data/lib/samagotchi/tools/execute.rb

@@ -203,8 +203,9 @@ module Samagotchi
           # Ended right at the deadline: finished, not timed out.
           timed_out = false if timed_out && !wait_thr.alive?
           if timed_out && on_timeout == :task
-            text = hand_over(id: id, command: command, cwd: cwd, pid: pid, waiter: wait_thr, started_at: started_at,
-                             timeout_sec: timeout_sec, dir: dir, logs: logs, exit_code_path: exit_code_path)
+            task = TaskRecord.running(id: id, command: command, cwd: cwd, pid: pid, started_at: started_at.utc.iso8601,
+                                      output_path: logs[0], stderr_path: logs[1], exit_code_path: exit_code_path)
+            text = hand_over(task, waiter: wait_thr, timeout_sec: timeout_sec, dir: dir)
             if text
               handed_over = true
               Log.info(:turn, "execute_handed_over", id: id, after_sec: timeout_sec)
@@ -337,25 +338,24 @@ module Samagotchi
       private_class_method :read_log
 
       # A command still running at the limit becomes a task (TaskRuntime.
-      # adopt) with the logs where they are; a back-pointer in its dir names
-      # the record for the sweep. nil when it can't be adopted (the caller
+      # adopt +task+, a TaskRecord.running) with the logs where they are
+      # (+dir+); a back-pointer in that dir names the record for the sweep. nil when it can't be adopted (the caller
       # then kills it as in :kill mode) or when it ended meanwhile (the
       # caller then reads it as finished).
       # @return [String, nil] the HANDED_OVER result
-      def self.hand_over(id:, command:, cwd:, pid:, waiter:, started_at:, timeout_sec:, dir:, logs:, exit_code_path:)
+      def self.hand_over(task, waiter:, timeout_sec:, dir:)
         return nil unless waiter.alive?
 
-        record, error = TaskRuntime.adopt(id: id, command: command, cwd: cwd, pid: pid, started_at: started_at,
-                                          output_path: logs[0], stderr_path: logs[1], exit_code_path: exit_code_path)
+        record, error = TaskRuntime.adopt(task)
         return nil if error
 
-        File.write(File.join(dir, BACK_POINTER), File.expand_path(TaskRuntime.metadata_path(record["id"])))
-        write_missing_exit_code(waiter, exit_code_path)
+        File.write(File.join(dir, BACK_POINTER), File.expand_path(TaskRuntime.metadata_path(record.id)))
+        write_missing_exit_code(waiter, record.exit_code_path)
         # Ended between the deadline and the adopt: the record says how.
-        TaskRuntime.get_record(id) unless waiter.alive?
-        lines = [handed_over_line(timeout_sec), "task_id: #{id}",
+        TaskRuntime.get_record(record.id) unless waiter.alive?
+        lines = [handed_over_line(timeout_sec), "task_id: #{record.id}",
                  "Wait for it with task_wait (it may take minutes); task_stop stops it."]
-        { "stdout" => logs[0], "stderr" => logs[1] }.each do |label, path|
+        { "stdout" => record.output_path, "stderr" => record.stderr_path }.each do |label, path|
           tail = TaskRuntime.output_tail_lines(path, HAND_OVER_TAIL_LINES)
           lines << "#{label} (so far, tail):\n#{tail.chomp}" unless tail.empty?
         end

data/lib/samagotchi/tools/registry.rb

@@ -85,7 +85,7 @@ module Samagotchi
       end
 
       # Every tool +source+ registered, declared or not (a plugin's tool set
-      # changing: Plugin::Api.apply_tools).
+      # changing: Plugin::ToolSpec.apply).
       # @return [Array<Entry>]
       def by_source(source) = @entries.values.select { |entry| entry.source == source }
 

data/lib/samagotchi/tools/task_create.rb

@@ -15,12 +15,12 @@ module Samagotchi
         return error if error
 
         [
-          "task_id: #{record.fetch("id")}",
-          "status: #{record.fetch("status")}",
-          "pid: #{record.fetch("pid")}",
-          "created_at: #{record.fetch("created_at")}",
-          "output_path: #{record.fetch("output_path")}",
-          "cwd: #{record.fetch("cwd")}"
+          "task_id: #{record.id}",
+          "status: #{record.status}",
+          "pid: #{record.pid}",
+          "created_at: #{record.created_at}",
+          "output_path: #{record.output_path}",
+          "cwd: #{record.cwd}"
         ].join("\n")
       rescue StandardError => e
         "Error: #{e.message}"

data/lib/samagotchi/tools/task_get.rb

@@ -20,20 +20,20 @@ module Samagotchi
 
       def self.format_record(record)
         [
-          "task_id: #{record.fetch("id")}",
-          "status: #{record.fetch("status")}",
-          "command: #{record.fetch("command")}",
-          "cwd: #{record.fetch("cwd")}",
-          "pid: #{record.fetch("pid")}",
-          "created_at: #{record.fetch("created_at")}",
-          "started_at: #{record.fetch("started_at")}",
-          "finished_at: #{record["finished_at"]}",
-          "exit_code: #{record["exit_code"]}",
-          "stop_reason: #{record["stop_reason"]}",
-          "output_path: #{record.fetch("output_path")}",
+          "task_id: #{record.id}",
+          "status: #{record.status}",
+          "command: #{record.command}",
+          "cwd: #{record.cwd}",
+          "pid: #{record.pid}",
+          "created_at: #{record.created_at}",
+          "started_at: #{record.started_at}",
+          "finished_at: #{record.finished_at}",
+          "exit_code: #{record.exit_code}",
+          "stop_reason: #{record.stop_reason}",
+          "output_path: #{record.output_path}",
           # A handed-over execute's stderr has a log of its own.
-          ("stderr_path: #{record["stderr_path"]}" if record["stderr_path"]),
-          (TaskRuntime::USER_STOP_NOTE if TaskRuntime.stopped_by_user?(record))
+          ("stderr_path: #{record.stderr_path}" if record.stderr_path),
+          (TaskRuntime::USER_STOP_NOTE if record.stopped_by_user?)
         ].compact.join("\n")
       end
       private_class_method :format_record

data/lib/samagotchi/tools/task_list.rb

@@ -21,12 +21,12 @@ module Samagotchi
 
       def self.format_entry(record)
         [
-          "task_id: #{record.fetch("id")}",
-          "status: #{record.fetch("status")}",
-          "pid: #{record.fetch("pid")}",
-          "created_at: #{record.fetch("created_at")}",
-          "command: #{preview(record.fetch("command"))}",
-          "output_path: #{record.fetch("output_path")}"
+          "task_id: #{record.id}",
+          "status: #{record.status}",
+          "pid: #{record.pid}",
+          "created_at: #{record.created_at}",
+          "command: #{preview(record.command)}",
+          "output_path: #{record.output_path}"
         ].join("\n")
       end
       private_class_method :format_entry

data/lib/samagotchi/tools/task_record.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Tools
+    # A background task's record, as TaskRuntime keeps it in
+    # tmp/tasks/<id>/task.json. Read with .from_file, written with #to_file;
+    # an update is a #with. The values are as on disk: times are iso8601
+    # strings, +pid+ whatever the file holds (a hand-edited one may not be
+    # a number; TaskRuntime never signals that).
+    #
+    # The file keeps its key order (the members' order) and leaves out the
+    # optional keys while unset: +stderr_path+ and +handed_over_by+ (only a
+    # handed-over execute has them) and +stop_requested_by+ (only once a
+    # stop started). bundles/slow-commands reads these files on its own.
+    TaskRecord = Data.define(
+      :metadata_version, :id, :command, :cwd, :workspace_root, :status, :pid, :pid_started,
+      :created_at, :started_at, :finished_at, :exit_code, :stop_reason,
+      :output_path, :stderr_path, :exit_code_path, :handed_over_by, :stop_requested_by
+    ) do
+      self::METADATA_VERSION = 1
+      self::OPTIONAL = %i[stderr_path handed_over_by stop_requested_by].freeze
+
+      # A record for a task that just started (task_create), or that an
+      # execute hands over (TaskRuntime.adopt fills in +pid_started+ then).
+      # @param started_at [String] iso8601; also its +created_at+
+      def self.running(id:, command:, cwd:, pid:, started_at:, output_path:, exit_code_path:, pid_started: nil,
+                       stderr_path: nil, handed_over_by: nil)
+        new(metadata_version: self::METADATA_VERSION, id: id, command: command, cwd: cwd, workspace_root: Dir.pwd,
+            status: "running", pid: pid, pid_started: pid_started, created_at: started_at, started_at: started_at,
+            finished_at: nil, exit_code: nil, stop_reason: nil, output_path: output_path, stderr_path: stderr_path,
+            exit_code_path: exit_code_path, handed_over_by: handed_over_by, stop_requested_by: nil)
+      end
+
+      # @param data [Hash] the parsed task.json; a key it lacks reads nil
+      # @return [TaskRecord, nil] nil when +data+ isn't an object
+      def self.from_file(data)
+        return nil unless data.is_a?(Hash)
+
+        new(**members.to_h { |key| [key, data[key.to_s]] })
+      end
+
+      # @return [Hash] the task.json object, string keys in member order
+      def to_file
+        to_h.reject { |key, value| value.nil? && self.class::OPTIONAL.include?(key) }.transform_keys(&:to_s)
+      end
+
+      def running? = status == "running"
+
+      def stopped_by_user? = stop_reason == "stopped_by_user"
+    end
+  end
+end