samagotchi 0.34.0 → 0.36.0

data/lib/samagotchi/worker_inbound.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "securerandom"
+require "time"
+
+require_relative "client_id"
+require_relative "config"
+require_relative "context_note"
+require_relative "log"
+require_relative "session"
+require_relative "session_inbox"
+
+module Samagotchi
+  # What comes into a worker's session between turns, each kind with its
+  # own save rule (the Worker runs the turns they start):
+  #
+  # - context notes (#absorb_notes): into the conversation, saved, then
+  #   their files deleted;
+  # - attached context (#absorb_context): once the conversation started,
+  #   saved, then the subscriptions written; a source asking to wake may
+  #   start a context wake turn (a ContextWake);
+  # - the first prompt (#take_initial_prompt): taken once and saved
+  #   cleared; as a command (#initial_command?) the session is saved idle;
+  # - an input file (#take_input): a Prompt for a turn, whose own save is
+  #   the turn's, or a command queued.
+  class WorkerInbound
+    # One context wake per source in this long (D5): later changes inside
+    # it arrive as notes.
+    CONTEXT_WAKE_WINDOW = 600
+
+    # A prompt to run a turn for: an input file's, or the first prompt.
+    # +no_interrupt+: an offer its turn makes keeps it for its continue
+    # turn; +images+: its image refs ({file:, name:}).
+    Prompt = Data.define(:text, :origin, :no_interrupt, :images) do
+      def initialize(text:, origin: nil, no_interrupt: false, images: []) = super
+    end
+
+    # A context wake turn to run: the ContextAbsorber::Delivery that woke
+    # it, whose wake note is already in the conversation as the start of
+    # the turn +turn_id+.
+    ContextWake = Data.define(:delivery, :turn_id) do
+      def name = delivery.name
+      def origin = { client_id: "#{ClientId::CONTEXT_PREFIX}#{name}" }
+    end
+
+    # A save between turns (the turn's own, a command's, the notes', the
+    # first prompt's): what it saves is in memory, so one that fails (disk
+    # full, permissions; the next save writes it) is logged and must not
+    # take the worker down with it.
+    # @param at [Symbol] which save, for the log
+    # @return [Boolean] whether it saved
+    def self.save_or_log(at)
+      yield
+      true
+    rescue SystemCallError, IOError => e
+      Log.exception(:worker, "save_failed", e, at: at)
+      false
+    end
+
+    # @param wakes [WorkerWakes] the wake budget a context wake asks
+    # @param awaiting_continue [#call] whether a continue offer waits
+    # @param stopped [#call] whether the session was stopped on disk
+    # @param queue_command [#call] (line, client_id) queues a session
+    #   command for the loop's next pass
+    def initialize(session:, state_dir:, session_dir:, engine:, context_absorber:, wakes:, awaiting_continue:,
+                   stopped:, queue_command:)
+      @session = session
+      @state_dir = state_dir
+      @session_dir = session_dir
+      @engine = engine
+      @context_absorber = context_absorber
+      @wakes = wakes
+      @awaiting_continue = awaiting_continue
+      @stopped = stopped
+      @queue_command = queue_command
+      @initial_prompt_taken = false
+    end
+
+    # Add the queued context notes to the conversation (between turns only,
+    # on the loop's thread), save, then delete their files: a crash before
+    # the delete leaves them claimed, and Engine#add_context_note skips a
+    # note the saved conversation already holds. A failed save keeps the
+    # files too: the next pass claims them again, finds them in the
+    # conversation and saves again. Not activity: a note alone neither
+    # starts a turn nor keeps an idle worker up.
+    def absorb_notes
+      files = SessionInbox.find_new_note_files(@session_dir)
+      return if files.empty? || @stopped.call
+
+      claimed = files.filter_map { |file| SessionInbox.claim_note_file(file) }
+      claimed.each do |file|
+        note = SessionInbox.read_note(file)
+        @engine.add_context_note(@session, note) if note
+      end
+      return unless save(:notes)
+
+      claimed.each { |file| FileUtils.rm_f(file) }
+    end
+
+    # The attached context's notes (ContextAbsorber), between turns. Not
+    # into a session with no turn yet (+before_turn+: one is about to
+    # run): auto-attached context alone doesn't make a session worth
+    # keeping. Saved, then the subscriptions written (a crash between the
+    # two re-delivers; the note ids dedupe).
+    # +wake+: the session is idle with nothing queued, so an update whose
+    # source asked to wake may start a turn (#context_wake_for): its note
+    # goes in as the turn's first message.
+    # @return [ContextWake, nil] the wake turn to run now
+    # @raise [SystemCallError, IOError] the caller logs it (context_failed)
+    def absorb_context(before_turn: false, wake: false)
+      return nil unless before_turn || conversation_started?
+      return nil if @stopped.call
+
+      batch = @context_absorber.pending
+      return nil unless batch
+
+      waking = wake ? context_wake_for(batch) : nil
+      turn_id = SecureRandom.uuid if waking
+      batch.deliveries.each do |delivery|
+        next unless delivery.note
+
+        note = delivery == waking ? delivery.wake_note.merge(turn_start: true, turn_id: turn_id) : delivery.note
+        @engine.add_context_note(@session, note)
+      end
+      # Saved even when every note was there already: after a failed save
+      # they are in memory only.
+      return nil if batch.notes.any? && !save(:context)
+
+      @context_absorber.commit(waking ? woken(batch, waking) : batch)
+      waking && ContextWake.new(delivery: waking, turn_id: turn_id)
+    end
+
+    # A failed wake turn kept nothing but its note: the update 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)
+      messages = @engine.messages_checkpoint
+      index = messages.index { |m| m[:turn_start] && m[:turn_id] == context_wake.turn_id }
+      return unless index
+
+      messages[index] = ContextNote.message(**context_wake.delivery.note)
+      @engine.rollback_to(messages)
+    end
+
+    # spawn_session hands the first prompt over in last_prompt, but
+    # last_prompt also records every later turn's prompt (and mark_error's
+    # reason), so only a session with no conversation yet has one pending; a
+    # resumed session must not replay its last turn. Taken once.
+    # @return [String, nil]
+    def take_initial_prompt
+      return nil if @initial_prompt_taken
+
+      @initial_prompt_taken = true
+      # A context note may have come before the first prompt ran.
+      return nil unless @session.messages.all? { |m| ContextNote.note?(m) } && !@session.last_prompt.to_s.strip.empty?
+
+      prompt = @session.last_prompt
+      @session.last_prompt = ""
+      save(:initial_prompt)
+      prompt
+    end
+
+    # The first prompt as a command (queued): the session was saved as
+    # running for a turn that won't run.
+    # @return [Boolean] whether it was one
+    def initial_command?(prompt)
+      return false unless queue_as_command(prompt, nil)
+
+      @session.status = Session::STATUS_IDLE
+      save(:initial_command, unless_stopped: true)
+      true
+    end
+
+    # Claim +input_file+ and yield its Prompt (the turn runs in the block),
+    # deleting the claimed file after. Nothing is yielded for a file
+    # another reader claimed, an empty line or a command (queued).
+    def take_input(input_file)
+      claimed_file = SessionInbox.claim_input_file(input_file)
+      return unless claimed_file
+
+      begin
+        message, origin, no_interrupt, images = SessionInbox.read_input(claimed_file)
+        return if message.to_s.strip.empty?
+        return if Array(images).empty? && queue_as_command(message, origin)
+
+        yield Prompt.new(text: message, origin: origin, no_interrupt: !!no_interrupt, images: images || [])
+      ensure
+        FileUtils.rm_f(claimed_file)
+      end
+    end
+
+    # Whether the session has had a turn: a user or assistant message.
+    def conversation_started?
+      Array(@session.messages).any? { |m| %w[user assistant model].include?((m[:role] || m["role"]).to_s) }
+    end
+
+    private
+
+    # +unless_stopped+: not when the session was stopped meanwhile: the stop
+    # (chi stop, from another process) saved its status, and this save
+    # would write the worker's over it.
+    def save(at, unless_stopped: false)
+      self.class.save_or_log(at) do
+        @session.save(state_dir: @state_dir) unless unless_stopped && @stopped.call
+      end
+    end
+
+    # A session command sent as a message (chi send -m "/model x", a web
+    # page's first message) runs as the command, as the Bridge does for a
+    # POST /turn; an unknown /word stays a prompt. Queued: the loop's next
+    # pass runs it.
+    # @return [Boolean] whether +text+ was one
+    def queue_as_command(text, origin)
+      return false unless @engine.command_registry.command?(text.to_s)
+
+      @queue_command.call(text, origin&.dig(:client_id))
+      true
+    end
+
+    # The update in +batch+ that may start a wake turn now: its source
+    # asked (wake: true), context.wake is on, the wake budget is open
+    # (WorkerWakes#context_open?: no continue offer, not paused, under
+    # session.max_wakes, past the start grace) and the source hasn't woken
+    # the session in the last CONTEXT_WAKE_WINDOW. The others stay plain
+    # notes. Within the start grace a change is a note: it came while the
+    # session was away.
+    def context_wake_for(batch, now: Time.now)
+      candidates = batch.deliveries.select(&:wake_note)
+      return nil if candidates.empty? || !context_wakes_on?
+      return nil unless @wakes.context_open?(awaiting_continue: @awaiting_continue.call, names: candidates.map(&:name))
+
+      candidates.find { |delivery| !woke_lately?(delivery.subscription, now) }
+    end
+
+    def context_wakes_on? = Config.get("context.wake") != false
+
+    def woke_lately?(subscription, now)
+      at = subscription&.wakes_at && Time.iso8601(subscription.wakes_at)
+      at ? now - at < CONTEXT_WAKE_WINDOW : false
+    rescue ArgumentError
+      false
+    end
+
+    # +batch+ with +waking+'s subscription recording the wake (the 10-minute window).
+    def woken(batch, waking)
+      stamped = waking.with(subscription: waking.subscription.with(wakes_at: Time.now.iso8601))
+      batch.with(deliveries: batch.deliveries.map { |delivery| delivery == waking ? stamped : delivery })
+    end
+  end
+end

data/lib/samagotchi/worker_wakes.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+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
+  # 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).
+  class WorkerWakes
+    # @param grace [Numeric] seconds after the start with no wake turn
+    # @param clock [#call] monotonic seconds
+    # @param max [#call, nil] the budget; nil reads session.max_wakes
+    def initialize(grace:, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, max: nil)
+      @grace = grace
+      @clock = clock
+      @max = max
+      @started_at = clock.call
+      @in_a_row = 0
+      @paused = false
+      @budget_noticed = false
+      @handed = nil
+    end
+
+    # Wake turns run since the last human input.
+    attr_reader :in_a_row
+
+    def paused? = @paused
+
+    def grace_left = @grace - (@clock.call - @started_at)
+
+    def in_grace? = grace_left.positive?
+
+    def max
+      return @max.call if @max
+
+      value = Integer(Config.get(ChildRing::MAX_WAKES_KEY), exception: false)
+      value&.positive? ? value : ChildRing::MAX_WAKES_DEFAULT
+    rescue StandardError
+      ChildRing::MAX_WAKES_DEFAULT
+    end
+
+    # For delegate reports: :due when a wake turn may run now (the block
+    # says reports wait; asked only when nothing else holds), :budget when
+    # only the budget stops it, nil otherwise. The start grace is the
+    # caller's (it shortens the idle sleep instead).
+    def delegate_state(awaiting_continue:)
+      return nil if @paused || awaiting_continue
+      return nil unless yield
+
+      @in_a_row < max ? :due : :budget
+    end
+
+    # For an attached context source asking to wake: no continue offer,
+    # not paused, past the start grace and under the budget. +names+: the
+    # sources asking, for the log line when the budget holds them.
+    def context_open?(awaiting_continue:, names:)
+      return false if @paused || awaiting_continue || in_grace?
+
+      if @in_a_row >= max
+        Log.info(:worker, "context_wake_held", reason: "max_wakes", names: names.join(","))
+        return false
+      end
+      true
+    end
+
+    # A wake turn starts. @return [Integer] the wake turns in a row now
+    def count! = @in_a_row += 1
+
+    # A wake turn failed: none starts again until a human's input.
+    def pause!
+      @paused = true
+    end
+
+    # A human's input resets the budget, the pause and the budget notice.
+    def human_input!
+      @in_a_row = 0
+      @paused = false
+      @budget_noticed = false
+    end
+
+    # @return [Boolean] true the first time the budget is spent since the
+    #   last human input: the UIs hear it once
+    def notice_budget!
+      return false if @budget_noticed
+
+      @budget_noticed = true
+    end
+
+    # The idle loop's sleep: +poll+, or less while a wake (the block says
+    # one is due) waits out the start grace.
+    def idle_wait(poll)
+      left = grace_left
+      left.positive? && yield ? [left, poll].min : poll
+    end
+
+    # The reports a delegate wake turn runs for, until its first boundary
+    # takes them (#take_handed); #drop_handed when the turn is over.
+    def hand_over(reports)
+      @handed = reports
+    end
+
+    # @return [Array, nil] the handed reports, once
+    def take_handed
+      reports = @handed
+      @handed = nil
+      reports
+    end
+
+    def drop_handed
+      @handed = nil
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.36.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -123,6 +123,7 @@ files:
 - README.md
 - bin/chi
 - docs/architecture.md
+- docs/broadcast.md
 - docs/cli.md
 - docs/configuration.md
 - docs/context.md
@@ -163,6 +164,10 @@ files:
 - lib/samagotchi/bridge_client.rb
 - lib/samagotchi/bridge_client/event_stream.rb
 - lib/samagotchi/bridge_client/sse_parser.rb
+- lib/samagotchi/broadcast/recipients.rb
+- lib/samagotchi/broadcast/scope_card.rb
+- lib/samagotchi/broadcast/tags.rb
+- lib/samagotchi/broadcast_command.rb
 - lib/samagotchi/bundle_command.rb
 - lib/samagotchi/bundle_needs.rb
 - lib/samagotchi/bundles/btw/manifest.yml
@@ -245,6 +250,7 @@ files:
 - lib/samagotchi/events.rb
 - lib/samagotchi/gem_update.rb
 - lib/samagotchi/generation_phase.rb
+- lib/samagotchi/git_head.rb
 - lib/samagotchi/guardrail_wiring.rb
 - lib/samagotchi/guardrails.rb
 - lib/samagotchi/guardrails/approval.rb
@@ -328,6 +334,7 @@ files:
 - lib/samagotchi/models_command.rb
 - lib/samagotchi/muted_memories.rb
 - lib/samagotchi/note_command.rb
+- lib/samagotchi/note_delivery.rb
 - lib/samagotchi/output_formatter.rb
 - lib/samagotchi/owner_lock.rb
 - lib/samagotchi/parent_report.rb
@@ -456,6 +463,7 @@ files:
 - lib/samagotchi/vision_support.rb
 - lib/samagotchi/waiting_steer.rb
 - lib/samagotchi/web/app.rb
+- lib/samagotchi/web/capabilities.rb
 - lib/samagotchi/web/info_probe.rb
 - lib/samagotchi/web/lan.rb
 - lib/samagotchi/web/markdown_renderer.rb
@@ -476,11 +484,14 @@ files:
 - lib/samagotchi/web/public/ctx.js
 - lib/samagotchi/web/public/data.js
 - lib/samagotchi/web/public/diff_view.js
+- lib/samagotchi/web/public/families_view.js
 - lib/samagotchi/web/public/format.js
 - lib/samagotchi/web/public/hold.js
 - lib/samagotchi/web/public/images.js
 - lib/samagotchi/web/public/index.html
 - lib/samagotchi/web/public/init_row.js
+- lib/samagotchi/web/public/live_timing.js
+- lib/samagotchi/web/public/live_turn.js
 - lib/samagotchi/web/public/model_pick.js
 - lib/samagotchi/web/public/model_picker.js
 - lib/samagotchi/web/public/notifications.js
@@ -504,6 +515,7 @@ files:
 - lib/samagotchi/web/public/thinking_ticker.js
 - lib/samagotchi/web/public/timing.js
 - lib/samagotchi/web/public/turn_events.js
+- lib/samagotchi/web/public/turn_html.js
 - lib/samagotchi/web/public/turn_model.js
 - lib/samagotchi/web/public/turn_view.js
 - lib/samagotchi/web/public/update_notice.js
@@ -514,7 +526,9 @@ files:
 - lib/samagotchi/web/token.rb
 - lib/samagotchi/worker.rb
 - lib/samagotchi/worker_idle_exit.rb
+- lib/samagotchi/worker_inbound.rb
 - lib/samagotchi/worker_sidecar.rb
+- lib/samagotchi/worker_wakes.rb
 homepage: https://github.com/dm1try/samagotchi
 licenses:
 - MIT