samagotchi 0.66.0 → 0.67.0

data/lib/samagotchi/send_command.rb

@@ -40,7 +40,7 @@ module Samagotchi
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...
              chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [--thinking LEVEL] [--toolkit NAME] [-m TEXT] [--image PATH]...
-             chi send --new --continues (ID|PREFIX|last:ID) [-m TEXT] [--image PATH]...
+             chi send --new --continues (ID|PREFIX|last:ID) [--model M] [-m TEXT] [--image PATH]...
              chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
              chi send --queue --wait [--timeout S] [--format json] [-m TEXT] ID
              chi send --wait [--timeout S] [--format json] ID
@@ -63,9 +63,11 @@ module Samagotchi
                     the current one
         --continues ID
                     (--new) start the next link of that session's chain:
-                    in its folder, on its model, LLM context,
-                    thinking level and toolkit, with a note carrying its recap; it
-                    is archived. last:ID names the chain's latest link.
+                    in its folder, on its model (or --model's; one whose
+                    host is gone falls back to the default, with a
+                    warning), LLM context, thinking level and toolkit,
+                    with a note carrying its recap; it is archived.
+                    last:ID names the chain's latest link.
                     Without -m the new session waits idle. Refused for a
                     session continued already (naming the next link) or
                     with delegates still open
@@ -289,11 +291,11 @@ module Samagotchi
       return usage_error("--new takes no session ids: it starts one session") unless options[:ids].empty?
 
       if options[:continues]
-        taken = [("--dir" if options[:dir]), ("--model" if options[:model])] +
+        taken = [("--dir" if options[:dir])] +
                 LLM_CONTEXT_FLAGS.filter_map { |key, flag| flag if options[key] } + [("--thinking" if options[:thinking])] +
                 [("--toolkit" if options[:toolkit])] + TOOLKIT_FLAGS.filter_map { |key, flag| flag unless Array(options[key]).empty? }
         unless taken.compact.empty?
-          return usage_error("--continues takes the previous session's folder, model, LLM context, thinking level and " \
+          return usage_error("--continues takes the previous session's folder, LLM context, thinking level and " \
                              "toolkit; " \
                              "leave out #{taken.compact.join(", ")}")
         end
@@ -358,7 +360,8 @@ module Samagotchi
       begin
         start = through_worker ? { prompt: nil, title: prompt } : { prompt: prompt }
         session = if options[:continues]
-                    SessionManager.continue_session(options[:continues], **start, state_dir: @state_dir)
+                    SessionManager.continue_session(options[:continues], **start, model: options[:model],
+                                                                             state_dir: @state_dir)
                   else
                     SessionManager.spawn_session(**start, working_directory: options[:dir],
                                                           model_name: options[:model],
@@ -388,15 +391,22 @@ module Samagotchi
                                  timeout: options[:timeout])
     end
 
-    # --continues: the model the new link will run (the previous link's),
-    # for the images check; [nil, nil] without --continues.
+    # The model the new session will run, for the images check: --model
+    # (nil: the default), or with --continues the one the new link will run
+    # (SessionContinue.model_for: --model's, else the previous link's, else
+    # the default it falls back to).
     # @return [Array, false] [model_name, model_typed], or false after the
-    #   error line (no such session)
+    #   error line (no such session, a model it can't start on)
     def continued_model(options)
       return [options[:model], nil] unless options[:continues]
 
       previous = Session.load(SessionChain.resolve(options[:continues], state_dir: @state_dir), state_dir: @state_dir)
-      [previous.model_name, previous.model_typed]
+      choice = SessionContinue.model_for(previous, options[:model])
+      inherited = options[:model].to_s.strip.empty? && choice.warning.nil?
+      inherited ? [previous.model_name, previous.model_typed] : [choice.model, nil]
+    rescue ModelProfile::MissingModel => e
+      error_line("chi send: could not start a session: #{e.message}")
+      false
     rescue ArgumentError => e
       error_line("chi send: #{e.message}")
       false

data/lib/samagotchi/session_continue.rb

@@ -56,11 +56,21 @@ module Samagotchi
     # moved the chain's end while it waited for the lock.
     TRIES = 3
 
+    # The model a new link runs on (#model_for): the name to spawn it with,
+    # and why it isn't the previous link's (nil when it is, or was given).
+    ModelChoice = Data.define(:model, :warning)
+    # What #check! decided before anything changes: the delegates to move
+    # (ChildMove::Plan) and the new link's model (ModelChoice).
+    Checked = Data.define(:plan, :choice)
+
     # Start the next link of a chain: a new session that continues
     # +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). The previous link is archived
+    # link's recap (SessionChain.note_text). +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
     # first, with its finished delegates (archive_session's rules: a turn
     # running, a prompt queued or the step-limit question refuse; an idle
     # worker is stopped), so a refusal starts nothing. Its open delegates
@@ -81,7 +91,7 @@ module Samagotchi
     # @raise [Refused] continued already, delegates open that can't
     #   move, or its folder is gone
     # @raise [ArchiveRefused, OwnedByTUI] as archive_session
-    def self.run(id_or_ref, prompt: nil, title: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5)
+    def self.run(id_or_ref, prompt: nil, title: nil, model: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5)
       sd = state_dir || Session.default_state_dir
       TRIES.times do |try|
         id = SessionChain.resolve(id_or_ref, state_dir: sd)
@@ -89,7 +99,7 @@ module Samagotchi
           follow = id_or_ref.to_s.strip.start_with?(SessionChain::LAST_PREFIX) && try < TRIES - 1
           next :moved if follow && SessionChain.next_of(id, state_dir: sd)
 
-          run_locked(id, prompt: prompt, title: title, state_dir: sd, recap_wait: recap_wait,
+          run_locked(id, prompt: prompt, title: title, model: model, state_dir: sd, recap_wait: recap_wait,
                          archive_wait: archive_wait)
         end
         return result unless result == :moved
@@ -105,9 +115,10 @@ module Samagotchi
       end
     end
 
-    private_class_method def self.run_locked(id, prompt:, title:, state_dir:, recap_wait:, archive_wait:)
+    private_class_method def self.run_locked(id, prompt:, title:, model:, state_dir:, recap_wait:, archive_wait:)
       previous = Session.load(id, state_dir: state_dir)
-      plan = check!(previous, state_dir)
+      checked = check!(previous, state_dir, model: model)
+      plan = checked.plan
       # archive_session's refusals that can be known now, before the wait.
       SessionManager.archivable!(id, state_dir, except: plan.move)
       recap_before_archive(id, state_dir, wait: recap_wait)
@@ -120,7 +131,8 @@ module Samagotchi
       archive = SessionManager.archive_session(id, state_dir: state_dir, wait: archive_wait, except: plan.move)
       archived = archive[:archived] - already
       begin
-        spawn_continuation(previous, prompt: prompt, title: title, state_dir: state_dir, move: plan.move)
+        spawn_continuation(previous, prompt: prompt, title: title, choice: checked.choice, state_dir: state_dir,
+                                     move: plan.move)
       rescue StandardError
         # Nothing started: the delegates go back, what this archived goes
         # back to the lists, and a new link saved before its worker failed
@@ -181,7 +193,7 @@ module Samagotchi
 
     # The new link, holding off any worker but its own (ChildMove.starting?)
     # while +move+ goes to it.
-    private_class_method def self.spawn_continuation(previous, prompt:, title:, state_dir:, move:)
+    private_class_method def self.spawn_continuation(previous, prompt:, title:, choice:, state_dir:, move:)
       recap = RecapStore.read(Session.session_dir(previous.id, state_dir: state_dir))
       start = prompt.to_s.strip.empty? ? nil : prompt
       title = previous.first_preview if title.to_s.strip.empty? && start.nil?
@@ -191,33 +203,64 @@ module Samagotchi
       end
       link = SessionManager.spawn_session(
         prompt: start, title: title, working_directory: previous.working_directory,
-        model_name: previous.model_typed || previous.model_name, setup: SessionSetup.of(previous),
+        model_name: choice.model, setup: SessionSetup.of(previous),
         continues: previous.id, note: SessionChain.note_text(previous, recap: recap),
         note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn
       )
       link.moved_children = move
+      # The fallback's warning first: spawn_session set its own.
+      warnings = [choice.warning, link.model_warning].compact
+      link.model_warning = warnings.join("; ") unless warnings.empty?
       link
     end
 
+    # The model a new link of +previous+'s chain runs on: +given+ when
+    # there is one (its host checked: ModelProfile::UnknownHost as for a new
+    # session), else the previous link's, as typed (so an alias holds). An
+    # inherited one whose host can't run it any more (gone from config.yml,
+    # disabled, an alias naming another host: UnknownHost) falls back to the
+    # default, with a warning naming why. `chi send --new --continues`
+    # judges images by it before #run decides the same.
+    # @param previous [Session]
+    # @param given [String, nil] blank: inherit
+    # @return [ModelChoice]
+    # @raise [ModelProfile::MissingModel] a +given+ model it can't run, or
+    #   a fallback with no default configured (or the default's host can't run it)
+    def self.model_for(previous, given)
+      unless given.to_s.strip.empty?
+        return ModelChoice.new(model: ModelProfile.check_host!(ModelProfile.required_model_name(given.strip)),
+                               warning: nil)
+      end
+
+      inherited = ModelProfile.required_model_name(previous.model_typed || previous.model_name)
+      begin
+        ModelChoice.new(model: ModelProfile.check_host!(inherited), warning: nil)
+      rescue ModelProfile::UnknownHost => e
+        default = ModelProfile.check_host!(ModelProfile.required_model_name(nil))
+        ModelChoice.new(model: default, warning: "#{inherited} can't run (#{e.message}); started on #{default}")
+      end
+    end
+
     # The refusals that come before anything changes: continued already (no
     # forks in a chain), an open delegate that can't move to the new link
     # (ChildMove.plan), the folder gone (the worker would run elsewhere), a
-    # model whose host config.yml no longer has.
-    # @return [ChildMove::Plan]
+    # given model whose host config.yml doesn't have, or an inherited one
+    # that can't run with no default to fall back to (#model_for).
+    # @return [Checked]
     # @raise [Refused, ModelProfile::MissingModel]
-    private_class_method def self.check!(previous, state_dir)
+    private_class_method def self.check!(previous, state_dir, model: nil)
       if (following = SessionChain.next_of(previous.id, state_dir: state_dir))
         raise Refused.new(previous.id, :continued, ids: [following])
       end
 
       plan = move_plan!(previous.id, state_dir)
-      # Its model's host, as SessionManager.spawn_session checks it: before
-      # the archive stops the previous link's worker.
-      ModelProfile.check_host!(ModelProfile.required_model_name(previous.model_typed || previous.model_name))
+      # The new link's model, its host checked as SessionManager.spawn_session
+      # checks it: before the archive stops the previous link's worker.
+      choice = model_for(previous, model)
       dir = previous.working_directory.to_s
       raise Refused.new(previous.id, :folder_gone, detail: dir) unless File.directory?(dir)
 
-      plan
+      Checked.new(plan: plan, choice: choice)
     end
 
     # A child still open below a session (#open_children); why: running,

data/lib/samagotchi/session_inbox.rb

@@ -236,15 +236,6 @@ module Samagotchi
       UNREADABLE_INPUT
     end
 
-    # Whether an unclaimed input file carries images (a mid-turn drain
-    # leaves it for its own turn).
-    def self.input_has_images?(input_file)
-      data = JSON.parse(File.read(input_file))
-      data.is_a?(Hash) && Array(data["images"]).any?
-    rescue JSON::ParserError, SystemCallError
-      false
-    end
-
     # Whether a mid-turn drain leaves this unclaimed input file for a turn
     # of its own instead of merging it at a step boundary: a queued message
     # (`delivery: queue`) or an image message (steering merges text only).
@@ -258,10 +249,6 @@ module Samagotchi
       false
     end
 
-    # Whether an input file carrying +enqueued_id+ still waits unclaimed in
-    # input/ (no worker has taken it for a turn or a step yet).
-    def self.input_waiting?(session_dir, enqueued_id) = !waiting_input(session_dir, enqueued_id).nil?
-
     # How the unclaimed input file carrying +enqueued_id+ waits: :turn_end
     # (a queue or an image message: it runs as a turn of its own, never
     # merged, #waits_for_turn_end?), :merges (a running turn's drain may

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