samagotchi 0.90.0 → 0.91.0

data/lib/samagotchi/worker.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "securerandom"
 
 require_relative "client_id"
 require_relative "config"
@@ -31,6 +32,9 @@ require_relative "child_reports"
 require_relative "child_move"
 require_relative "context_absorber"
 require_relative "context_poller"
+require_relative "kernel_loop"
+require_relative "task_finish_note"
+require_relative "task_watch"
 require_relative "tools/task_runtime"
 
 module Samagotchi
@@ -74,6 +78,8 @@ module Samagotchi
     # How much of a command's output goes into its :command_ran.
     COMMAND_OUTPUT_LIMIT = 4096
     BUSY_OUTPUT = "busy: wait for the turn to end"
+    # /exit held by background tasks a finish wake waits for: how to end them.
+    TASK_STOP_HINT = "stop one with the web's stop-task button or by asking for task_stop"
     # !rollback mid-turn would mean "the turn I'm in".
     ROLLBACK_BUSY_OUTPUT = "busy: Ctrl-C the turn first, then !rollback"
     # How long a signalled worker's turn has to end (it is canceled at once,
@@ -242,7 +248,7 @@ module Samagotchi
       # a command queued mid-turn (/thinking, /model, /llm-context) changes
       # what it starts with: no turn-end warm-up then.
       @engine.next_turn_waiting = lambda {
-        !@command_queue.empty? || SessionInbox.find_new_input_files(@session_dir).any? || wake_due?
+        !@command_queue.empty? || SessionInbox.find_new_input_files(@session_dir).any? || wake_due? || task_wake_due?
       }
       @turn_flow = TurnFlow.new(engine: @engine)
       # Its question's answer is queued as the matching /continue (the
@@ -258,6 +264,9 @@ module Samagotchi
       # The seq of the last turn's end event: a command queued before it was
       # queued while that turn ran.
       @turn_end_seq = 0
+      # The background tasks this session started and hasn't seen finish:
+      # one that finishes unseen wakes the idle session (#run_task_wake).
+      @task_watch = TaskWatch.new
       @engine.subscribe(observer: lambda { |event|
         if Events::TURN_END.include?(event[:type])
           @turn_end_seq = event[:event_seq]
@@ -269,6 +278,7 @@ module Samagotchi
           @turn_ending = false
         end
         ring_question(event) if event[:type] == :question_requested
+        watch_tasks(event)
       })
       # This session's own delegate children's news (rings in children/).
       @child_reports = ChildReports.new(session_id: @session_id, state_dir: @state_dir,
@@ -315,7 +325,10 @@ module Samagotchi
         timeout_minutes: @idle_exit_minutes || SessionManager.config_idle_exit_minutes,
         input_pending: -> { !@command_queue.empty? || !SessionInbox.find_new_input_files(@session_dir).empty? },
         awaiting_continue: -> { @turn_flow.awaiting_continue? },
-        running_tasks: -> { Tools::TaskRuntime.running_created_in(@engine.messages_checkpoint) }
+        running_tasks: -> { Tools::TaskRuntime.running_created_in(@engine.messages_checkpoint) },
+        # Only when a finish would wake the session (D3): with queue its end
+        # is just a note, not worth keeping the worker up for.
+        watched_tasks: -> { TaskWatch.mode == "wake" ? @task_watch.running : [] }
       )
     end
 
@@ -371,12 +384,13 @@ module Samagotchi
       run_input_files(input_files)
     end
 
-    # Nothing queued: a delegate wake turn or a due reminder runs, else
-    # the worker leaves when the idle exit or a client's exit is due, else
-    # it sleeps until woken or the fallback tick.
+    # Nothing queued: a delegate wake turn, a task finish wake turn or a due
+    # reminder runs, else the worker leaves when the idle exit or a client's
+    # exit is due, else it sleeps until woken or the fallback tick.
     # @return [Symbol, nil] as #pass
     def idle_pass
       return if run_wake_turn
+      return if run_task_wake
       return if run_due_reminders
       return left(:idle_exit) if @idle_exit.due? && leave_idle
       return left(@exit_restart ? :restart : :exit_requested) if @exit_requested && leave_on_request
@@ -441,6 +455,9 @@ module Samagotchi
         memories: @session.preloaded_memory_names,
         muted_memories: @session.muted_memory_names,
         appended_prompt_files: @session.appended_prompt_files,
+        # The finish wake reports a task the model leaves running: the tool
+        # descriptions say so, fixed for this worker (a stable prompt prefix).
+        task_finish_notes: TaskWatch.mode != "off",
         reminders: {
           callback: lambda { |due_names|
             # A reminder is due: the loop runs a reminder turn for it once
@@ -552,8 +569,10 @@ module Samagotchi
     # @param prompt [WorkerInbound::Prompt]
     def run_prompt(prompt)
       origin = prompt.origin
-      # A first turn sees the context attached before it.
+      # A first turn sees the context attached before it, and any turn the
+      # background tasks that finished since the last look.
       absorb_context(before_turn: true)
+      absorb_task_notes
       user_input(origin&.dig(:client_id))
       @continue_offer.drop(origin)
       @turn_flow.before_prompt_turn
@@ -647,6 +666,153 @@ module Samagotchi
       @wakes.drop_handed
     end
 
+    # The Engine's raw events feed the task watch (session.task_wakes not
+    # off): a result that started a task or showed its end, a turn's start,
+    # a user's Stop of it (M5).
+    def watch_tasks(event)
+      case event[:type]
+      when :tool_call_completed then @task_watch.observe(event) unless TaskWatch.mode == "off"
+      when :turn_started then @task_watch.turn_started
+      when :turn_canceled then @task_watch.turn_canceled(event[:cancellation_reason])
+      end
+    end
+
+    # Whether a finished task would start a wake turn now: the Engine skips
+    # the turn-end warm-up then (next_turn_waiting).
+    def task_wake_due?
+      TaskWatch.mode == "wake" && @task_watch.any? && @wakes.task_open?(awaiting_continue: @turn_flow&.awaiting_continue?) &&
+        @task_watch.finished?
+    end
+
+    # The background tasks this session started that finished unseen
+    # (TaskWatch#take_finished), each as a TASK FINISHED note
+    # (TaskFinishNote): the first one not note-only starts a wake turn from
+    # task:<id> when session.task_wakes is wake, nothing is queued, no exit
+    # was asked for and the wake budget is open (WorkerWakes#task_open?);
+    # the others, and every one otherwise, are plain notes for the next
+    # turn (M2). A spent budget is announced once.
+    # @return [Boolean] whether a wake turn ran
+    def run_task_wake
+      return false if @wakes.in_grace? || !@task_watch.any?
+
+      finished = take_finished_tasks
+      return false if finished.empty?
+
+      waking = finished.find { |entry, _| !entry.note_only } if task_wake_open?
+      task_wake = note_finished_tasks(finished, waking: waking)
+      return false if task_wake == :failed
+
+      save_or_log(:task_notes) { save_session }
+      unless task_wake
+        task_budget_notice(finished.count { |entry, _| !entry.note_only }) if TaskWatch.mode == "wake" && @wakes.spent?
+        return false
+      end
+
+      run_task_wake_turn(task_wake)
+      true
+    end
+
+    # Before a prompt's turn: the finished tasks join it as plain notes.
+    def absorb_task_notes
+      return unless @task_watch.any?
+
+      finished = take_finished_tasks
+      return if finished.empty?
+      return if note_finished_tasks(finished) == :failed
+
+      save_or_log(:task_notes) { save_session }
+    end
+
+    # Each finished task's note into the conversation: +waking+'s as the
+    # wake turn's start, the others plain. A note that can't be written (a
+    # log that can't be read, say) puts it and the ones after it back in
+    # the watch for the next look.
+    # @return [WorkerInbound::TaskWake, nil, :failed]
+    def note_finished_tasks(finished, waking: nil)
+      written = []
+      (finished - [waking]).each do |entry, record|
+        add_task_note(entry, record)
+        written << entry
+      end
+      waking && add_task_wake_note(*waking)
+    rescue StandardError => e
+      Log.warn(:worker, "task_note_failed", error: e.class.name, msg: e.message)
+      @task_watch.put_back(finished.map(&:first) - written)
+      :failed
+    end
+
+    # Only the tasks the conversation still holds (a !rollback, a restored
+    # turn may have dropped the result that started one). A failure to
+    # read them is logged: they wait for the next look.
+    def take_finished_tasks
+      @task_watch.take_finished(keep: Tools::TaskRuntime.created_ids_in(@engine.messages_checkpoint))
+    rescue StandardError => e
+      Log.warn(:worker, "task_watch_failed", error: e.class.name, msg: e.message)
+      []
+    end
+
+    def task_wake_open?
+      TaskWatch.mode == "wake" && nothing_queued? && !@exit_requested &&
+        @wakes.task_open?(awaiting_continue: @turn_flow.awaiting_continue?)
+    end
+
+    def task_note(entry, record, wake:, turn_id: nil)
+      TaskFinishNote.note(record, limit_sec: entry.limit_sec, wake: wake, turn_id: turn_id,
+                                  cap: KernelLoop.resolve_output_char_cap(nil))
+    end
+
+    def add_task_note(entry, record)
+      @engine.add_context_note(@session, task_note(entry, record, wake: false))
+    end
+
+    # The wake note, in the conversation as the wake turn's first message
+    # (before TurnFlow#before_prompt_turn, so a restore keeps it).
+    # @return [WorkerInbound::TaskWake]
+    def add_task_wake_note(entry, record)
+      turn_id = SecureRandom.uuid
+      @engine.add_context_note(@session, task_note(entry, record, wake: true, turn_id: turn_id))
+      WorkerInbound::TaskWake.new(ids: [entry.id], turn_id: turn_id, plain_note: task_note(entry, record, wake: false))
+    end
+
+    # A turn nobody typed for a finished task: a continue turn from
+    # task:<id> whose first message is the wake note, on the delegate wake's
+    # rules (counted toward session.max_wakes). A failure that kept nothing,
+    # or a Stop that restored the conversation, leaves the note as a plain
+    # one (WorkerInbound#unmark_wake) and pauses wakes until a human's input (M4).
+    def run_task_wake_turn(task_wake)
+      Log.info(:worker, "task_wake_turn", task_id: task_wake.ids.first, in_a_row: @wakes.count!)
+      @turn_flow.before_prompt_turn
+      restores = @turn_flow.restores
+      run_engine_turn(nil, continue: true, origin: task_wake.origin, id: task_wake.turn_id,
+                           max_iterations: IterationLimit.for) do |result, error|
+        if error
+          kept = @turn_flow.prompt_turn_failed(
+            error: error, wake: "a finished background task (#{task_wake.name.delete_prefix("task ")})",
+            wake_kept: "Its note stays for the user's next message."
+          ) == :kept
+          @inbound.unmark_wake(task_wake) unless kept
+          @wakes.pause!
+        else
+          @continue_offer.after_turn(result)
+          if result.canceled? && @turn_flow.restores != restores
+            @inbound.unmark_wake(task_wake)
+            @wakes.pause!
+          end
+        end
+      end
+    end
+
+    # The wake budget is spent: the UIs hear once that finished tasks wait
+    # as notes (one notice per stretch, shared with the other kinds).
+    def task_budget_notice(count)
+      return unless count.positive? && @wakes.notice_budget!
+
+      @engine.announce(type: :hook_notice, hook: "task", level: :info, between_turns: true,
+                       text: "#{count} finished background task#{"s" if count != 1} noted; the model reads " \
+                             "#{count == 1 ? "it" : "them"} with your next message " \
+                             "(#{@wakes.max} wake turn#{"s" if @wakes.max != 1} in a row, #{ChildRing::MAX_WAKES_KEY})")
+    end
+
     # The idle loop's sleep: the fallback tick, or less while reports wait
     # out the start grace.
     def idle_wait = @wakes.idle_wait(@poll_interval) { wake_state == :due }
@@ -1200,12 +1366,16 @@ module Samagotchi
     # +delete+: the session is deleted after (/exit --delete), so no recap.
     # +restart+: a new worker takes over (on the newest chi installed), so
     # WorkerIdleExit#hold_for_restart's rules, and no recap or discard.
-    # @return [Symbol, nil] what keeps the worker up, nil when it will leave
+    # @return [Symbol, Hash, nil] what keeps the worker up ({reason:
+    #   :background_tasks, tasks:} names the watched tasks still running),
+    #   nil when it will leave
     def exit_request(client_id, delete: false, restart: false)
       # The Bridge serves before the idle-exit policy exists.
       return :starting unless @idle_exit
 
       hold = restart ? @idle_exit.hold_for_restart : @idle_exit.hold_for_request(requester: client_id)
+      # /exit names the tasks it waits for (D3).
+      return { reason: hold, tasks: @task_watch.running, hint: TASK_STOP_HINT } if hold == :background_tasks && !restart
       return hold if hold
 
       @exit_requested = true

data/lib/samagotchi/worker_idle_exit.rb

@@ -13,6 +13,8 @@ module Samagotchi
   # * a reminder is registered. Reminders live only in the Engine and repeat
   #   until the agent cancels them, so an exit would drop them for good;
   # * a continue offer waits for an answer; it too lives only in memory;
+  # * a background task the worker watches for a finish wake (TaskWatch)
+  #   still runs: its end would go unnoticed after an exit (D3);
   # * less than the timeout has passed since the worker started, the Engine's
   #   last activity, or the last client request or disconnect.
   #
@@ -29,15 +31,18 @@ module Samagotchi
     # @param awaiting_continue [#call] true while a continue offer waits
     # @param running_tasks [#call] the background tasks this conversation
     #   started that still run (Tools::TaskRuntime.running_created_in)
+    # @param watched_tasks [#call] the ones a finish wake watches that still
+    #   run (TaskWatch#running): they hold the idle exit and /exit too
     # @param clock [#call] monotonic seconds, the Engine's and Bridge's clock
     def initialize(engine:, bridge:, timeout_minutes:, input_pending:, awaiting_continue: -> { false },
-                   running_tasks: -> { [] }, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+                   running_tasks: -> { [] }, watched_tasks: -> { [] }, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       @engine = engine
       @bridge = bridge
       @timeout = timeout_minutes.to_f * 60
       @input_pending = input_pending
       @awaiting_continue = awaiting_continue
       @running_tasks = running_tasks
+      @watched_tasks = watched_tasks
       @clock = clock
       @started_at = clock.call
     end
@@ -49,7 +54,8 @@ module Samagotchi
 
     # What keeps the worker up, or nil when nothing does.
     # @return [Symbol, nil] :disabled, :turn_running, :input_queued,
-    #   :continue_offered, :client_connected, :reminders or :recent_activity
+    #   :continue_offered, :client_connected, :reminders, :background_tasks
+    #   or :recent_activity
     def hold
       return :disabled unless @timeout.positive?
       return :turn_running if @engine.turn_running?
@@ -57,6 +63,7 @@ module Samagotchi
       return :continue_offered if @awaiting_continue.call
       return :client_connected if @bridge && @bridge.open_streams.positive?
       return :reminders if @engine.reminder_store&.any?
+      return :background_tasks if @watched_tasks.call.any?
       return :recent_activity if idle_seconds < @timeout
 
       nil
@@ -71,13 +78,14 @@ module Samagotchi
     #   either (the last check before leaving, when the asker's stream may
     #   still be open, untagged)
     # @return [Symbol, nil] :turn_running, :input_queued, :continue_offered,
-    #   :client_connected or :reminders
+    #   :client_connected, :reminders or :background_tasks
     def hold_for_request(requester:, streams: true)
       return :turn_running if @engine.turn_running?
       return :input_queued if @input_pending.call
       return :continue_offered if @awaiting_continue.call
       return :client_connected if streams && @bridge && @bridge.open_streams_except(requester).positive?
       return :reminders if @engine.reminder_store&.any?
+      return :background_tasks if @watched_tasks.call.any?
 
       nil
     end

data/lib/samagotchi/worker_inbound.rb

@@ -11,6 +11,7 @@ require_relative "context_note"
 require_relative "log"
 require_relative "session"
 require_relative "session_inbox"
+require_relative "tools/task_record"
 require_relative "worker_wakes"
 
 module Samagotchi
@@ -51,6 +52,19 @@ module Samagotchi
       # that agrees closes the round and counts toward session.max_wakes only.
       def peer_turn? = peer? && !delivery.agreed
       def origin = { client_id: "#{ClientId::CONTEXT_PREFIX}#{name}" }
+      # The plain note #unmark_wake puts back.
+      def note = delivery.note
+    end
+
+    # A task finish wake turn to run (TaskWatch, TaskFinishNote): its wake
+    # note is in the conversation as the start of the turn +turn_id+;
+    # +plain_note+ is the same note without the turn start or the ask, which
+    # #unmark_wake puts back after a failed or restored wake turn. +ids+: the
+    # finished tasks it runs for (the first one names it).
+    TaskWake = Data.define(:ids, :turn_id, :plain_note) do
+      def name = "task #{Tools::TaskRecord.short_id(ids.first)}"
+      def origin = { client_id: "#{ClientId::TASK_PREFIX}#{ids.first}" }
+      def note = plain_note
     end
 
     # A save between turns (the turn's own, a command's, the notes', the
@@ -144,13 +158,13 @@ module Samagotchi
 
     # A failed wake turn kept nothing but its note: the note goes back to
     # a plain note (no turn start, the background wording), so a reload
-    # draws no empty turn for it.
-    def unmark_wake(context_wake)
+    # draws no empty turn for it. +wake+: a ContextWake or a TaskWake.
+    def unmark_wake(wake)
       messages = @engine.messages_checkpoint
-      index = messages.index { |m| m[:turn_start] && m[:turn_id] == context_wake.turn_id }
+      index = messages.index { |m| m[:turn_start] && m[:turn_id] == wake.turn_id }
       return unless index
 
-      messages[index] = ContextNote.message(**context_wake.delivery.note)
+      messages[index] = ContextNote.message(**wake.note)
       @engine.rollback_to(messages)
     end
 

data/lib/samagotchi/worker_wakes.rb

@@ -6,10 +6,10 @@ require_relative "child_reports"
 
 module Samagotchi
   # A worker's wake budget: turns nobody typed (a delegate report's wake
-  # turn, an attached context source's) run only past the start grace, at
-  # most session.max_wakes in a row with no human input, and not after a
-  # failed one until a human's input (a provider outage doesn't loop).
-  # Shared by both kinds of wake; the Worker asks it before each and tells
+  # turn, a finished background task's, an attached context source's) run
+  # only past the start grace, at most session.max_wakes in a row with no
+  # human input, and not after a failed one until a human's input (a
+  # provider outage doesn't loop). Shared by every kind of wake; the Worker asks it before each and tells
   # it what happened. It also holds the reports a delegate wake turn was
   # started for until the turn's first boundary takes them (#hand_over,
   # #take_handed).
@@ -110,6 +110,16 @@ module Samagotchi
       true
     end
 
+    # For a background task that finished unseen (TaskWatch): no continue
+    # offer, not paused, past the start grace and under the budget. #count!
+    # when its wake turn starts.
+    def task_open?(awaiting_continue:)
+      !@paused && !awaiting_continue && !in_grace? && @in_a_row < max
+    end
+
+    # Whether wakes are paused (a failed wake turn) until a human's input.
+    def paused? = @paused
+
     # A wake turn starts; +peer+: for a peer's answer, which counts toward
     # both budgets. @return [Integer] the wake turns in a row now
     def count!(peer: false)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.90.0
+  version: 0.91.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -520,6 +520,8 @@ files:
 - lib/samagotchi/steer_cut.rb
 - lib/samagotchi/steer_cut_after.rb
 - lib/samagotchi/system_prompt.rb
+- lib/samagotchi/task_finish_note.rb
+- lib/samagotchi/task_watch.rb
 - lib/samagotchi/terminal_ui.rb
 - lib/samagotchi/terminal_ui/attach_launcher.rb
 - lib/samagotchi/terminal_ui/attached_loop.rb