samagotchi 0.90.0 → 0.91.0

data/lib/samagotchi/task_finish_note.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "context_note"
+require_relative "tool_output_cut"
+require_relative "tools/task_wait"
+
+module Samagotchi
+  # The note a finished background task leaves in its session (TaskWatch,
+  # the Worker's finish wake): a context note under its own header
+  # (ContextNote::TASK_HEADER), as Engine#add_context_note takes it. The
+  # wake variant opens a wake turn (turn_start, turn_id) and ends with the
+  # ask (WAKE_TEXT); the plain one joins the next turn (queue mode, a spent
+  # budget, a note-only task, the unmark after a failed wake).
+  module TaskFinishNote
+    WAKE_TEXT = "chi started this turn because a background task you started finished; your user didn't write " \
+                "anything.\nCarry on with what you planned to do with its result. If you planned nothing, tell your " \
+                "user in a sentence or two how it went."
+
+    module_function
+
+    # @param record [Tools::TaskRecord] the finished task
+    # @param limit_sec [Integer, nil] the limit an execute handed it over at
+    # @param wake [Boolean] the wake variant
+    # @param cap [Integer] max_tool_output_chars: task_wait's text is cut to
+    #   it as ToolRunner cuts the tool's result
+    # @return [Hash] the note (ContextNote.message's keys)
+    def note(record, limit_sec:, wake:, cap:, turn_id: nil, now: Time.now)
+      note = { note_id: "task-#{record.id}", source: "task #{short_id(record.id)}", header: ContextNote::TASK_HEADER,
+               text: text(record, limit_sec: limit_sec, wake: wake, cap: cap), created_at: now.iso8601 }
+      wake ? note.merge(turn_start: true, turn_id: turn_id) : note
+    end
+
+    def text(record, limit_sec:, wake:, cap:)
+      [headline(record, limit_sec), "command: #{record.command}", body(record, cap), (WAKE_TEXT if wake)].compact.join("\n")
+    end
+
+    def headline(record, limit_sec)
+      seconds = duration(record)
+      outcome = record.exit_code.nil? ? record.status.to_s : "exit #{record.exit_code}"
+      handed = " (handed over by execute at its #{limit_sec}s limit)" if limit_sec
+      "Background task #{short_id(record.id)} finished: #{outcome}#{" after #{duration_text(seconds)}" if seconds}#{handed}."
+    end
+
+    # task_wait's own text for the task, cut to +cap+ as its result would be
+    # (ToolOutputCut's :head_tail_ref, naming the logs).
+    def body(record, cap)
+      text = Tools::TaskWait.finished_text(record).to_s
+      return text if text.length <= cap
+
+      ToolOutputCut.apply(text, cap: cap, tool: Tools::TaskWait::NAME, ref: record.output_path,
+                                ref_stderr: record.stderr_path).first
+    end
+
+    # From started_at to the exit_code file's mtime (the shell's EXIT trap
+    # wrote it as it ended), else finished_at: that is when a refresh first
+    # noticed the end, which may be long after. nil when neither is known.
+    # @return [Float, nil] seconds
+    def duration(record)
+      started = time(record.started_at)
+      return nil unless started
+
+      ended = exit_code_mtime(record) || time(record.finished_at)
+      ended && [ended - started, 0].max
+    end
+
+    def duration_text(seconds)
+      seconds = seconds.round
+      return "#{seconds}s" if seconds < 60
+      return format("%dm%02ds", seconds / 60, seconds % 60) if seconds < 3600
+
+      format("%dh%02dm", seconds / 3600, (seconds % 3600) / 60)
+    end
+
+    def short_id(id) = Tools::TaskRecord.short_id(id)
+
+    def exit_code_mtime(record)
+      path = record.exit_code_path.to_s
+      path.empty? || !File.file?(path) ? nil : File.mtime(path)
+    rescue SystemCallError
+      nil
+    end
+
+    def time(value)
+      value && Time.iso8601(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/samagotchi/task_watch.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+require_relative "tools/task_runtime"
+
+module Samagotchi
+  # The background tasks a worker's session started that the model hasn't
+  # seen finish (docs/internals/background-tasks.md, Finish wake). Held by
+  # the Worker (the --no-shared REPL has none) and fed by the Engine's raw
+  # :tool_call_completed events (#observe), the input Bridge#own_task_ids
+  # reads too; the idle loop takes the finished ones (#take_finished) for a
+  # wake turn or a plain note. In memory only: a crash loses them, and they
+  # behave as before (the model sees them at its next look).
+  #
+  # Thread-safe: the turn thread feeds it, the loop's thread takes from it,
+  # and anytime commands run on threads of their own.
+  class TaskWatch
+    # A watched task: +limit_sec+, the limit an execute handed it over at
+    # (nil for task_create's); +note_only+, the user stopped the turn that
+    # started or waited on it (M5): its finish is a plain note, no wake.
+    Entry = Data.define(:id, :limit_sec, :note_only) do
+      def initialize(id:, limit_sec: nil, note_only: false) = super
+    end
+
+    # The cancel reasons that are the user's own Stop (Bridge::CANCEL_REASONS
+    # less session_stopped, and the TUI's ctrl_c).
+    USER_CANCEL_REASONS = %i[manual user ctrl_c].freeze
+
+    # The first line of a task tool's result, after a gate-corrected call's
+    # "ran as: …" line and the optional "[tool]" lead.
+    TASK_LINE = /\A#{Tools::TaskRuntime::RAN_AS_LINE}(?:\[task_(?:wait|get|stop)\]\n)?task_id: (\S+)/
+    LOOK_TOOLS = %w[task_wait task_get task_stop].freeze
+    HANDED_OVER_LIMIT = /#{Regexp.escape(Tools::Execute::HANDED_OVER)} (\d+)s limit/
+
+    MODE_KEY = "session.task_wakes"
+    MODES = %w[wake queue off].freeze
+
+    # session.task_wakes: wake (default), queue or off; anything else is wake.
+    def self.mode
+      value = Config.get(MODE_KEY).to_s
+      MODES.include?(value) ? value : "wake"
+    rescue StandardError
+      "wake"
+    end
+
+    def initialize
+      @mutex = Mutex.new
+      @entries = {}
+      @turn_ids = []
+    end
+
+    # A raw Engine event: a result that started a task adds it, one that
+    # shows the model the task's end removes it (#seen_id).
+    def observe(event)
+      return unless event[:type] == :tool_call_completed
+
+      tool = event[:tool].to_s
+      output = event[:output].to_s
+      output = output.scrub unless output.valid_encoding?
+      if (id = Tools::TaskRuntime.created_id(tool, output))
+        add(id, limit_sec: tool == Tools::Execute::NAME ? output[HANDED_OVER_LIMIT, 1]&.to_i : nil)
+      elsif LOOK_TOOLS.include?(tool) && (id = output[TASK_LINE, 1])
+        touched(id)
+        remove(id) if seen?(tool, output)
+      end
+    end
+
+    def add(id, limit_sec: nil)
+      @mutex.synchronize do
+        @entries[id] = Entry.new(id: id, limit_sec: limit_sec)
+        @turn_ids << id
+      end
+    end
+
+    def remove(id)
+      @mutex.synchronize { @entries.delete(id) }
+    end
+
+    # A turn begins: the tasks it starts or waits on are its own (#turn_canceled).
+    def turn_started
+      @mutex.synchronize { @turn_ids = [] }
+    end
+
+    # A turn ended canceled for +reason+: the user's Stop makes that turn's
+    # tasks note-only (M5); a signal's, a hook's or a session stop's don't.
+    def turn_canceled(reason)
+      return unless USER_CANCEL_REASONS.include?(reason&.to_sym)
+
+      @mutex.synchronize do
+        @turn_ids.each { |id| @entries[id] &&= @entries[id].with(note_only: true) }
+      end
+    end
+
+    def ids = @mutex.synchronize { @entries.keys }
+
+    def entry(id) = @mutex.synchronize { @entries[id] }
+
+    def any? = @mutex.synchronize { @entries.any? }
+
+    # The watched tasks that finished, taken out of the watch with their
+    # records ([Entry, TaskRecord], oldest first). One the user stopped (the
+    # web's stop-task button) or whose record is gone is dropped, not
+    # returned. +keep+: the ids the conversation still holds
+    # (TaskRuntime.created_ids_in): a !rollback or a restored turn may have
+    # dropped the result that added one, which is dropped too. One `ps` per
+    # running task (TaskRuntime.get_record); nothing with an empty watch.
+    # @return [Array<Array(Entry, Tools::TaskRecord)>]
+    def take_finished(keep: nil)
+      entries = @mutex.synchronize { @entries.values }
+      return [] if entries.empty?
+
+      entries.filter_map do |entry|
+        # Safe for any llm_context strategy: stale and forget stubs are drawn
+        # in the view sent to the model (LLMContextView, the entry's edits),
+        # never written over the saved tool_response text; only a !rollback
+        # or a restored turn takes the result that names the id out.
+        next drop(entry, log: "not_in_conversation") if keep && !keep.include?(entry.id)
+
+        record, error = Tools::TaskRuntime.get_record(entry.id)
+        next drop(entry) if error || record.nil?
+        next nil if record.running?
+        # Removed by a look meanwhile (a task_wait on an anytime command's thread).
+        next nil unless drop(entry, kept: true)
+        next nil if record.stopped_by_user?
+
+        [entry, record]
+      end
+    end
+
+    # +entries+ taken by #take_finished whose note couldn't be written:
+    # watched again (an id watched meanwhile keeps its own entry).
+    def put_back(entries)
+      @mutex.synchronize { entries.each { |entry| @entries[entry.id] ||= entry } }
+    end
+
+    # Whether a watched task has finished (#take_finished would take it):
+    # Engine#next_turn_waiting asks at a turn's end. Takes nothing.
+    def finished?
+      ids.any? do |id|
+        record, = Tools::TaskRuntime.get_record(id)
+        record && !record.running?
+      end
+    end
+
+    # The watched tasks still running ({id:, command:}), for the idle exit
+    # and /exit (WorkerIdleExit's running_tasks).
+    # @return [Array<Hash>]
+    def running
+      ids.filter_map do |id|
+        record, = Tools::TaskRuntime.get_record(id)
+        { id: id, command: record.command.to_s } if record&.running?
+      end
+    end
+
+    private
+
+    # Removes +entry+; nil (a filter_map's skip), or with +kept+ whether it
+    # was there. +log+: why a task leaves without a note (debug).
+    def drop(entry, kept: false, log: nil)
+      removed = !remove(entry.id).nil?
+      Log.debug(:worker, "task_watch_dropped", task_id: entry.id, reason: log) if log && removed
+      kept ? removed : nil
+    end
+
+    def touched(id)
+      @mutex.synchronize { @turn_ids << id unless @turn_ids.include?(id) }
+    end
+
+    # Whether +tool+'s +output+ for a task shows the model its end:
+    # task_wait's final status or a done_pattern match (D5), task_get's
+    # final status (the status alone is enough), any task_stop.
+    def seen?(tool, output)
+      status = output[/^status: (\S+)/, 1]
+      case tool
+      when "task_stop" then true
+      when "task_get" then final?(status)
+      when "task_wait" then final?(status) || output.match?(/^wait_result: pattern_matched$/)
+      else false
+      end
+    end
+
+    def final?(status) = !status.nil? && status != "running"
+  end
+end

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -60,8 +60,12 @@ module Samagotchi
       HELD_REASONS = {
         "turn_running" => "a turn is running", "input_queued" => "prompts are queued",
         "continue_offered" => "a continue offer is pending", "client_connected" => "another UI is attached",
-        "reminders" => "reminders are set", "starting" => "the worker is still starting"
+        "reminders" => "reminders are set", "starting" => "the worker is still starting",
+        "background_tasks" => "background tasks it started are still running"
       }.freeze
+      # How to end a background task that holds the worker up (an older
+      # worker's 409 has no hint of its own).
+      TASK_STOP_HINT = "stop one with the web's stop-task button or by asking for task_stop"
       # How much of the last answer a join shows.
       JOIN_ANSWER_LINES = 12
       JOIN_ANSWER_CHARS = 1200
@@ -556,7 +560,8 @@ module Samagotchi
           "Detached; the session's worker is stopping. Resume with: chi --resume #{id}"
         when 409
           reason = reply.json&.fetch("reason", nil).to_s
-          "Detached; the session keeps running (#{HELD_REASONS.fetch(reason, reason)}). Re-attach with: chi --attach #{id}"
+          "Detached; the session keeps running (#{held_words(reason, reply.json&.fetch("tasks", nil))}). " \
+            "Re-attach with: chi --attach #{id}"
         when 0 then exit_failed_line("no reply")
         when 408 then exit_failed_line(LATE)
         else
@@ -567,6 +572,14 @@ module Samagotchi
         end
       end
 
+      # Why the worker stayed up; the background tasks it waits for by
+      # their short id and command (a finish wake's, D3), and how to stop one.
+      def held_words(reason, tasks)
+        words = HELD_REASONS.fetch(reason, reason)
+        listed = Array(tasks).filter_map { |t| "#{Tools::TaskRecord.short_id(t["id"])} (#{t["command"]})" if t.is_a?(Hash) }
+        listed.empty? ? words : "#{words}: #{listed.join(", ")}; #{TASK_STOP_HINT}"
+      end
+
       # An older worker leaves the field out.
       def discards?(reply) = reply.json&.fetch("discard", nil) == true
 
@@ -1628,8 +1641,10 @@ module Samagotchi
       def reminder_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::SYSTEM_PREFIX)
       def report_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::CHILD_PREFIX)
       def context_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::CONTEXT_PREFIX)
-      # A turn with no prompt: "(continuing)"; a context wake's label alone.
-      def continuing_text(origin) = context_origin?(origin) ? nil : "(continuing)"
+      def task_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::TASK_PREFIX)
+      # A turn with no prompt: "(continuing)"; a context wake's or a task
+      # finish wake's label alone.
+      def continuing_text(origin) = context_origin?(origin) || task_origin?(origin) ? nil : "(continuing)"
     end
   end
 end

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -9,6 +9,7 @@ require_relative "../steer_cut"
 require_relative "../memory_bundle/index_size"
 require_relative "../prompt_note"
 require_relative "../prompt_files"
+require_relative "../tools/task_record"
 require_relative "model_segments_text"
 
 module Samagotchi
@@ -207,8 +208,9 @@ module Samagotchi
 
       # Who sent a line, by its client_id: CLIENT_LABELS by the whole id or
       # its prefix, a turn an attached context source started
-      # (context:<name>) as "context <name> changed", AUTOMATIC_LABEL for
-      # an id chi doesn't know; +fallback+ for none (the user's own).
+      # (context:<name>) as "context <name> changed", a finished background
+      # task's (task:<id>) as "task <id8> finished", AUTOMATIC_LABEL for an
+      # id chi doesn't know; +fallback+ for none (the user's own).
       def client_label(client_id, fallback = "user")
         return fallback unless client_id
 
@@ -216,6 +218,9 @@ module Samagotchi
         name = id.delete_prefix(ClientId::CONTEXT_PREFIX)
         return "context #{name} changed" if id.start_with?(ClientId::CONTEXT_PREFIX) && !name.empty?
 
+        task = id.delete_prefix(ClientId::TASK_PREFIX)
+        return "task #{Tools::TaskRecord.short_id(task)} finished" if id.start_with?(ClientId::TASK_PREFIX) && !task.empty?
+
         prefix = id[/\A[^:]*:/]
         CLIENT_LABELS[id] || (prefix && CLIENT_LABELS[prefix]) || AUTOMATIC_LABEL
       end

data/lib/samagotchi/tool_declarations.rb

@@ -518,6 +518,22 @@ module Samagotchi
 
     GEMMA_QUOTE = '<|"|>'
 
+    # What a worker's finish wake (session.task_wakes not off) lets the
+    # model know: a task it leaves running is reported when it ends.
+    TASK_FINISH_LINE = "if you end your turn before it finishes, chi tells you when it does."
+
+    # +schema+ with TASK_FINISH_LINE in execute's hand-over sentence and at
+    # task_create's end; any other schema as given.
+    def with_task_finish_line(schema)
+      case schema[:name]
+      when "execute"
+        schema.merge(description: schema[:description].sub("and task_wait waits for it.",
+                                                           "and task_wait waits for it; #{TASK_FINISH_LINE}"))
+      when "task_create" then schema.merge(description: "#{schema[:description]} #{TASK_FINISH_LINE.sub(/\Ai/, "I")}")
+      else schema
+      end
+    end
+
     # +schema+ without execute's description property: what a session
     # with execute.description off declares (the parameter isn't offered
     # at all). Any other schema as given.

data/lib/samagotchi/tools/builtins.rb

@@ -185,13 +185,17 @@ module Samagotchi
       #   description parameter (execute.description off)
       # @param policy [String, nil] llm_context.policy, the sentence
       #   forget_outputs' description carries
+      # @param task_finish_notes [Boolean] a worker's session whose finish
+      #   wake reports a task left running (session.task_wakes not off):
+      #   execute and task_create say so (ToolDeclarations::TASK_FINISH_LINE)
       # @return [Registry] a new registry with the built-ins, in
       #   TOOL_SCHEMAS order (an Engine's own, which bundles add to), then
       #   forget_outputs, offered only under the forget layer
-      def registry(command_description: true, policy: ToolDeclarations::FORGET_OUTPUTS_POLICY)
+      def registry(command_description: true, policy: ToolDeclarations::FORGET_OUTPUTS_POLICY, task_finish_notes: false)
         by_name = CLASSES.to_h { |klass| [klass::NAME, klass] }
         registry = ToolDeclarations::TOOL_SCHEMAS.each_with_object(Registry.new) do |schema, built|
           schema = ToolDeclarations.without_command_description(schema) unless command_description
+          schema = ToolDeclarations.with_task_finish_line(schema) if task_finish_notes
           klass = by_name.fetch(schema[:name])
           handler = HANDLERS.fetch(klass::NAME) { ->(call, _kctx) { klass.call(call[:content]) } }
           built.register(klass::NAME, schema: schema, handler: handler)

data/lib/samagotchi/tools/task_record.rb

@@ -44,6 +44,15 @@ module Samagotchi
         to_h.reject { |key, value| value.nil? && self.class::OPTIONAL.include?(key) }.transform_keys(&:to_s)
       end
 
+      # A task id as people read it: the random part a task_create id ends
+      # with (TaskRuntime.generate_task_id starts it with the time, the same
+      # for every task that second), else its first 8 chars. The web's
+      # turn_events.js has the JS twin (shortTaskId).
+      def self.short_id(id)
+        id = id.to_s
+        id[/-(\h{8})\z/, 1] || id[0, 8]
+      end
+
       def running? = status == "running"
 
       def stopped_by_user? = stop_reason == "stopped_by_user"

data/lib/samagotchi/tools/task_wait.rb

@@ -80,12 +80,19 @@ module Samagotchi
       end
       private_class_method :cancelled_response
 
-      # Always give the log's last lines: a test run's summary, an error. A
-      # task the user stopped also says so.
-      def self.finished_response(record, tail_lines)
+      # A finished task's text, as task_wait gives it: its status lines and
+      # always the log's last lines (a test run's summary, an error), then a
+      # stderr_tail when the record has a non-empty one. A task the user
+      # stopped also says so. Public: a task finish wake's note
+      # (TaskFinishNote) carries the same text.
+      # @param record [TaskRecord] a finished one
+      # @return [String] a RefText of its output_path when it has one
+      def self.finished_text(record, tail_lines: TAIL_LINES_DEFAULT)
         extra = record.stopped_by_user? ? [TaskRuntime::USER_STOP_NOTE] : []
         format_response(record, output_tail: output_tail(record, tail_lines), tail_lines: tail_lines, extra: extra)
       end
+
+      def self.finished_response(record, tail_lines) = finished_text(record, tail_lines: tail_lines)
       private_class_method :finished_response
 
       def self.output_tail(record, tail_lines)

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/web/public/notify.js

@@ -15,11 +15,11 @@ export function notifyState({ hasNotification, secureContext, permission, wanted
 }
 
 // A finished turn shorter than this was watched: no "done". Not a turn
-// chi ran for a delegate child's report (last_turn origin delegate_report)
-// or an attached context change (context): nobody started it, so nobody
-// watched it.
+// chi ran for a delegate child's report (last_turn origin delegate_report),
+// an attached context change (context) or a finished background task
+// (task): nobody started it, so nobody watched it.
 const DONE_MIN_SECONDS = 10;
-const UNWATCHED_ORIGINS = ["delegate_report", "context"];
+const UNWATCHED_ORIGINS = ["delegate_report", "context", "task"];
 
 // The step-limit question (kind "continue": a turn ran out of iterations
 // and asks whether to go on) has its own reason: "out of steps".

data/lib/samagotchi/web/public/turn_events.js

@@ -107,13 +107,25 @@ export function isReportClient(clientId) {
 
 // A turn chi ran because an attached context source changed: context:<name>.
 const CONTEXT_CLIENT = "context:";
+// A turn chi ran because a background task the session started finished
+// unseen: task:<task id> (the Worker's finish wake).
+const TASK_CLIENT = "task:";
+
+// A task id as people read it: the random part a task_create id ends with
+// (it starts with the time), else its first 8 chars (TaskRecord.short_id).
+function shortTaskId(id) {
+  const m = /-([0-9a-f]{8})$/i.exec(id);
+  return m ? m[1] : id.slice(0, 8);
+}
 
 // The label on another client's prompt, by its client_id prefix; a context
-// change's turn as "context <name> changed".
+// change's turn as "context <name> changed", a finished task's as
+// "task <id8> finished".
 export function clientLabel(clientId) {
   if (!clientId) return null;
   const id = String(clientId);
   if (id.startsWith(CONTEXT_CLIENT) && id.length > CONTEXT_CLIENT.length) return `context ${id.slice(CONTEXT_CLIENT.length)} changed`;
+  if (id.startsWith(TASK_CLIENT) && id.length > TASK_CLIENT.length) return `task ${shortTaskId(id.slice(TASK_CLIENT.length))} finished`;
   const colon = id.indexOf(":");
   return CLIENT_LABELS[id] || (colon >= 0 && CLIENT_LABELS[id.slice(0, colon + 1)]) || AUTOMATIC_LABEL;
 }