samagotchi 0.5.1 → 0.7.0

data/lib/samagotchi/plugin/api.rb

@@ -14,6 +14,7 @@ module Samagotchi
       COMMAND_NAME = %r{\A/[a-z][a-z0-9_-]{0,31}\z}
       TOOL_NAME = /\A[a-z][a-z0-9_]{0,47}\z/
       PARAM_NAME = /\A[a-z_][a-z0-9_]*\z/i
+      FAILED_STREAM_HOOK_LOG_SECONDS = 60
 
       # @param bundle [String]
       # @param label [String] "<file> (bundle <name>)": what hooks and
@@ -222,10 +223,17 @@ module Samagotchi
           label = @label
           block = hook[:block]
           context = @context
+          # A stream hook fires ~once a second: a broken one logs once a minute.
+          quiet_for = hook[:event] == :generation_progress ? FAILED_STREAM_HOOK_LOG_SECONDS : 0
+          logged_at = nil
           @registries.hooks.register_bundle(bundle, hook[:event], hook_name: label.split(" ").first,
                                                                   priority: hook[:priority]) do |event|
             block.call(event, context)
           rescue StandardError => e
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            next if logged_at && now - logged_at < quiet_for
+
+            logged_at = now
             # Logged only: a turn's live region is on screen.
             Log.warn(:plugins, "plugin_hook_failed", bundle: bundle, event: hook[:event].to_s, error: e.class.name,
                                                      msg: "#{label} #{hook[:event]} hook failed: #{e.message}")

data/lib/samagotchi/plugin/context.rb

@@ -18,10 +18,10 @@ module Samagotchi
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +model_name+ and +state_dir+ are what ctx.sessions forks with.
-    # +steer+ takes (text, source) and +stop_turn+ (reason, label), each
-    # true when it acted on a running turn.
+    # +steer+ takes (text, source), +stop_turn+ and +stop_generation+
+    # (reason, label), each true when it acted on a running turn.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
-                      :ask_model, :model_name, :state_dir, :scratch, :steer, :stop_turn, keyword_init: true)
+                      :ask_model, :model_name, :state_dir, :scratch, :steer, :stop_turn, :stop_generation, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -199,6 +199,15 @@ module Samagotchi
         !!@host.stop_turn&.call(reason.to_s, @label)
       end
 
+      # Cut the generation that is streaming, as a hook's
+      # event[:stop_generation] does: the turn goes on and the model is
+      # asked again (retry.empty_answer), or with no retry left the turn
+      # ends as cancelled (hook). Shows nothing: post your own notice.
+      # @return [Boolean] whether a streaming generation was cut now
+      def stop_generation(reason)
+        !!@host.stop_generation&.call(reason.to_s, @label)
+      end
+
       private
 
       def deep_freeze(value)

data/lib/samagotchi/plugin_tasks.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require_relative "cancellation_controller"
+require_relative "log"
+require_relative "plugin/api"
+
+module Samagotchi
+  # An Engine's plugin init tasks (chi.init) and the tool sets plugins stage
+  # (chi.replace_tools) for the turn thread.
+  #
+  # A plugin's slow setup (docs/plugins.md, Init tasks): run on its own
+  # thread once the owner can show it (#start!), announced as
+  # plugin_init_started / plugin_init_finished unless quiet. A turn waits
+  # for the running ones that provide tools before its first model request
+  # (#await), up to each one's timeout.
+  #
+  # What it needs from the Engine comes through lookups, called at use.
+  # Lock order: the Engine's lifecycle lock may be held when this one is
+  # taken (#shut_down!), the event lock too (#running); this lock is never
+  # held while the event lock is taken.
+  class PluginTasks
+    # +cancel+ is the task's own controller, cancelled only by #shut_down!:
+    # a Ctrl-C ends a turn's wait, not the task.
+    InitTask = Struct.new(:id, :bundle, :label, :plugin_label, :provides_tools, :quiet, :timeout, :failed, :block,
+                          :cancel, :thread, :state, :started_at, keyword_init: true) do
+      # What the task's block reads: whether chi is shutting down.
+      def cancelled? = cancel.cancelled?
+    end
+
+    # How long a task may hold a turn when it gives no timeout.
+    INIT_TASK_TIMEOUT = 60.0
+
+    INIT_WAIT_POLL = 0.05
+
+    # @param clock              [#call] → Float, monotonic seconds
+    # @param synchronize_events [#call] (&block) → runs the block holding the event log
+    # @param announce           [#call] (event) → announces an event
+    # @param emit               [#call] (sink, event) → emits to a turn's sink + observers
+    # @param show_card          [#call] (**card) → shows a card
+    # @param tools              [#call] → Tools::Registry
+    # @param notify             [#call] (text, level, source) → a notice
+    # @param tools_changed      [#call] → the tools changed (prompts built again)
+    def initialize(clock:, synchronize_events:, announce:, emit:, show_card:, tools:, notify:, tools_changed:)
+      @clock = clock
+      @synchronize_events = synchronize_events
+      @announce = announce
+      @emit = emit
+      @show_card = show_card
+      @tools = tools
+      @notify = notify
+      @tools_changed = tools_changed
+      @mutex = Mutex.new
+      @shut_down = false
+      @tasks = []
+      # Plugins' tool sets from chi.replace_tools, by bundle, until the
+      # turn thread applies them (#apply_staged_tools!).
+      @staged_tools = {}
+    end
+
+    # Add a plugin's init task (Plugin::Api#init at commit); it starts with
+    # #start!.
+    def add(bundle:, label:, plugin_label:, provides_tools:, quiet:, timeout:, failed: nil, &block)
+      @mutex.synchronize do
+        @tasks << InitTask.new(id: "#{bundle}-#{@tasks.size + 1}", bundle: bundle.to_s, label: label.to_s,
+                               plugin_label: plugin_label, provides_tools: provides_tools ? true : false,
+                               quiet: quiet ? true : false, timeout: timeout || INIT_TASK_TIMEOUT, failed: failed,
+                               block: block, cancel: CancellationController.new, state: :pending)
+      end
+      nil
+    end
+
+    # Start the init tasks not started yet, each on its own thread. The
+    # worker calls it once its Bridge is up, the REPL once it renders
+    # events, and every turn (a -p run has only that); later calls start
+    # nothing new.
+    def start!
+      @mutex.synchronize do
+        return if @shut_down
+
+        @tasks.each do |task|
+          next unless task.state == :pending
+
+          task.state = :starting
+          task.started_at = @clock.call
+          task.thread = Thread.new { run(task) }
+          task.thread.report_on_exception = false
+        end
+      end
+      nil
+    end
+
+    # The running init tasks a UI shows (not the quiet ones), for a UI that
+    # joins while they run (Bridge#snapshot, with the event log held).
+    # @return [Array<Hash>] {bundle:, id:, label:}
+    def running
+      @mutex.synchronize do
+        @tasks.select { |task| task.state == :running && !task.quiet }
+              .map { |task| { bundle: task.bundle, id: task.id, label: task.label } }
+      end
+    end
+
+    # Wait for the running init tasks that provide tools, each up to its
+    # timeout from its start, while +controller+ isn't cancelled; tell the
+    # turn's sink what it waits for (:plugin_init_wait). A task that ends
+    # late or fails leaves the turn without its tools.
+    # @return [Boolean] whether it waited
+    def await(controller = nil, on_event = nil)
+      waiting = @mutex.synchronize do
+        @tasks.select { |task| task.provides_tools && %i[starting running].include?(task.state) }
+      end
+      return false if waiting.empty?
+
+      @emit.call(on_event, { type: :plugin_init_wait,
+                             tasks: waiting.map { |task| { bundle: task.bundle, id: task.id, label: task.label } } })
+      started = @clock.call
+      loop do
+        now = @clock.call
+        left = waiting.select { |task| %i[starting running].include?(task.state) && now < task.started_at + task.timeout }
+        break if left.empty? || controller&.cancelled?
+
+        sleep(INIT_WAIT_POLL)
+      end
+      Log.info(:plugins, "init_wait", ms: ((@clock.call - started) * 1000).round,
+                                      cancelled: controller&.cancelled? ? true : nil)
+      true
+    end
+
+    # The init task this thread runs, or nil.
+    def current = Thread.current[:"samagotchi_init_#{object_id}"]
+
+    # Keep a plugin's new tool set (chi.replace_tools, from any thread)
+    # for the turn thread, which applies it (#apply_staged_tools!): the
+    # registry is read only there. A later set of the same bundle wins.
+    def stage_tools(bundle, specs, context)
+      @mutex.synchronize do
+        return if @shut_down
+
+        @staged_tools[bundle] = [specs, context]
+      end
+      nil
+    end
+
+    # Apply the staged tool sets (#stage_tools), on the turn thread, before
+    # the turn's system prompt is built; the prompts are built again when
+    # a set changed anything. A name another source has is left out with a
+    # notice.
+    # @return [Boolean] whether the tools changed
+    def apply_staged_tools!
+      staged = @mutex.synchronize do
+        taken = @staged_tools
+        @staged_tools = {}
+        taken
+      end
+      changed = false
+      staged.each do |bundle, (specs, context)|
+        result = Plugin::Api.apply_tools(@tools.call, bundle, specs, context)
+        changed ||= result[:changed]
+        result[:skipped].each do |why|
+          Log.warn(:plugins, "plugin_tool_skipped", bundle: bundle, msg: why)
+          @notify.call("#{why}; left out", :warn, bundle)
+        end
+        Log.info(:plugins, "plugin_tools_replaced", bundle: bundle, tools: specs.size) if result[:changed]
+      end
+      @tools_changed.call if changed
+      changed
+    end
+
+    # Shutting down (Engine#shutdown, under its lifecycle lock): nothing
+    # starts or stages after this; an init task's requests end (a server's
+    # boot), so it finishes.
+    # @return [Array<Thread>] the task threads, to join
+    def shut_down!
+      @mutex.synchronize do
+        @shut_down = true
+        @tasks.each { |task| task.cancel.cancel!(:shutdown) }
+        @tasks.filter_map(&:thread)
+      end
+    end
+
+    # After the joins: the task threads still alive are killed.
+    def kill_leftovers
+      @tasks.each { |task| task.thread&.kill if task.thread&.alive? }
+    end
+
+    # @return [Array<InitTask>] a copy of the task list (specs)
+    def tasks
+      @mutex.synchronize { @tasks.dup }
+    end
+
+    private
+
+    def run(task)
+      Thread.current[:"samagotchi_init_#{object_id}"] = task
+      @synchronize_events.call do
+        task.state = :running
+        @announce.call({ type: :plugin_init_started, bundle: task.bundle, id: task.id, label: task.label }) unless task.quiet
+      end
+      Log.info(:plugins, "init_started", bundle: task.bundle, id: task.id, label: task.label)
+      summary = task.block.call(task)
+      finish(task, ok: true, summary: summary.is_a?(String) ? summary : nil)
+    rescue StandardError => e
+      finish(task, ok: false, error: e.message)
+    end
+
+    def finish(task, ok:, summary: nil, error: nil)
+      Log.public_send(ok ? :info : :warn, :plugins, "init_finished", bundle: task.bundle, id: task.id, ok: ok,
+                                                                      ms: ((@clock.call - task.started_at) * 1000).round,
+                                                                      msg: error)
+      shut_down = @mutex.synchronize { @shut_down }
+      @synchronize_events.call do
+        task.state = ok ? :done : :failed
+        next if shut_down || (task.quiet && ok)
+
+        unless task.quiet
+          @announce.call({ type: :plugin_init_finished, bundle: task.bundle, id: task.id, label: task.label, ok: ok,
+                           summary: summary, error: error }.compact)
+        end
+        # A failure stays on screen (and for a UI that joins later) as a
+        # card: a short title (the card shows the bundle beside it), the
+        # detail in the body.
+        unless ok
+          title = task.failed || "setup failed"
+          body = task.failed ? error.to_s : "#{task.label}: #{error}"
+          @show_card.call(source: task.bundle, title: title, body: body, level: :warn, id: "init-#{task.id}")
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/question_desk.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+require "securerandom"
+require "time"
+
+require_relative "log"
+require_relative "tools/ask_user_question"
+
+module Samagotchi
+  # An Engine's question flow: the one open question (ask_user_question, a
+  # hook's ask_user, a guardrail approval), its answer and its cancel, shared
+  # by every UI. The turn thread blocks in #open_question; the UIs answer or
+  # cancel from theirs (a REPL answers inline through the sync handler).
+  #
+  # What it needs from the Engine comes through lookups, read at call time.
+  class QuestionDesk
+    # Raised by #answer when the question it targets is no longer open
+    # (never asked, superseded, already answered or cancelled). A subclass
+    # of ArgumentError for existing callers; transports map it to 409 Conflict.
+    class NotPending < ArgumentError; end
+
+    DISMISSED_NOTE = "The user dismissed the question without answering. Go on with your best judgement, " \
+                     "or ask in your reply if you can't."
+
+    # @param session           [#call] → Session, nil
+    # @param state_dir         [#call] → String, the session's state dir
+    # @param emit              [#call] (event) → emits an event to the turn sink + observers
+    # @param cancel_controller [#call] → CancellationController, nil (the running turn's)
+    # @param interface         [#call] → Symbol, the Engine's interface
+    # @param user_input        [#call] (session_id) → a human answered (ArchiveStore)
+    def initialize(session:, state_dir:, emit:, cancel_controller:, interface:, user_input:)
+      @session_lookup = session
+      @state_dir_lookup = state_dir
+      @emit = emit
+      @cancel_controller_lookup = cancel_controller
+      @interface_lookup = interface
+      @user_input = user_input
+      # A Monitor: re-entered by the specs from the same thread.
+      @lock = Monitor.new
+      @cv = @lock.new_cond
+      @pending = nil
+      @answer = nil
+      @sync_handler = nil
+    end
+
+    # @return [Hash, nil] current pending question (thread-safe copy)
+    def pending
+      @lock.synchronize { @pending&.dup }
+    end
+
+    # Ask the model's question (ask_user_question): the kernel's
+    # question_handler, called on the turn thread with the payload
+    # Tools::AskUserQuestion.validate made. Opens it (#open_question) and
+    # returns the answer as JSON for the tool result.
+    # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
+    # @return [String] normalized answer JSON
+    def request(payload)
+      result = open_question(**payload.slice(:question, :options, :header),
+                             multi_select: !!payload[:multi_select], allow_freeform: !!payload[:allow_freeform])
+      # Dismissed (the card's dismiss, Esc): an answer of its own, not a
+      # tool failure the model learns to avoid the tool from.
+      result = { dismissed: true, id: result[:id], note: DISMISSED_NOTE } if result.is_a?(Hash) && result[:error] == "no answer"
+      result.is_a?(String) ? result : JSON.generate(result)
+    end
+
+    # Open a question for the UIs and wait for its answer. Emits
+    # :question_requested, persists it to the session, and BLOCKS until
+    # answer / cancel wakes it (or the turn is cancelled).
+    # The fields go to pending as given (no cleaning), extra keys
+    # included, so a caller can add its own (kind:, approval:).
+    # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
+    # @return [Hash, String] the answer {id:, selected:, freeform:, selected_indices:},
+    #   or {error:, …}; a String when a sync handler returned text itself
+    def open_question(fields)
+      id = SecureRandom.uuid
+      pending = { id: id, **fields, status: "pending", created_at: Time.now.iso8601(3) }.compact
+
+      @lock.synchronize do
+        @pending = pending
+        @answer = nil
+      end
+      # Persist to session file for WEB stub + resume (generic for all UIs)
+      if session
+        session.pending_question = pending.dup
+        begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
+      end
+      # Generic emit for all UIs (TUI, WEB, Bridge, future). Observers that
+      # stash this event (e.g. TerminalUI handle_question_event) will
+      # discard it as stale if the synchronous handler below already answers
+      # and clears pending — see drain_pending_question? staleness check.
+      emit({ type: :question_requested, pending_question: pending })
+
+      # If a synchronous UI handler is registered (TUI), invoke it inline on the
+      # SAME thread that called request_question (TerminalUI's REPL thread is the
+      # turn thread — no second thread exists to answer). This avoids deadlock.
+      # This path is TUI-specific but the surrounding emit/clear is generic, so
+      # any future UI that registers a sync handler gets the same guarantee.
+      if @sync_handler
+        begin
+          sync_res = @sync_handler.call(pending.dup)
+          # Handler may have called answer_question or returned a hash/string.
+          # Decided under the lock; saved and announced after it (never emit
+          # holding the question lock: a snapshot holds the event lock and
+          # then reads #pending).
+          ans = @lock.synchronize do
+            if @answer
+              @pending = nil
+              @answer
+            elsif sync_res.is_a?(Hash) && sync_res[:selected]
+              # Treat returned hash as answer (handler rendered and parsed)
+              @answer = sync_res
+              @pending = nil
+              sync_res
+            end
+          end
+          if ans
+            clear_saved_question
+            emit({ type: :question_answered, id: id, answer: ans })
+            return ans
+          end
+          return sync_res if sync_res.is_a?(String) && !sync_res.strip.empty?
+        rescue StandardError => e
+          Log.warn(:turn, "question_handler_failed", echo: "[ask_user_question] sync handler failed: #{e.message}", error: e.class.name)
+        end
+        # Sync handler existed but did not produce an answer — do not deadlock on
+        # CV (no cross-thread answerer exists for synchronous UIs). Clear pending
+        # and return an error so the model can fallback to plain text. Generic
+        # observers will discard the stale question_requested via staleness check.
+        @lock.synchronize { @pending = nil }
+        clear_saved_question
+        return { error: "no answer", detail: "handler failed to capture selection", id: id }
+      end
+
+      # Block until answered/cancelled (cross-thread path: WEB/Bridge/background worker)
+      answer = nil
+      cancelled_reason = nil
+      @lock.synchronize do
+        loop do
+          break if @answer
+          break if cancel_controller&.cancelled?
+          break if @pending.nil? || @pending[:status] != "pending"
+
+          # Wait with timeout to check cancel; 0.2s matches reminder poll
+          @cv.wait(0.2)
+        end
+        answer = @answer
+        controller = cancel_controller
+        cancelled_reason = controller.reason.to_s if answer.nil? && controller&.cancelled?
+        @pending = nil
+      end
+      # Saved and announced outside the question lock (see the sync path).
+      clear_saved_question
+      if cancelled_reason
+        emit({ type: :question_cancelled, id: id, reason: cancelled_reason })
+        return { error: "cancelled", reason: cancelled_reason, id: id }
+      end
+
+      if answer
+        emit({ type: :question_answered, id: id, answer: answer })
+        answer
+      else
+        { error: "no answer", id: id }
+      end
+    end
+
+    # Answer the pending question (called from UI thread).
+    # @param id [String] pending id
+    # @param selected [Array<String>] values/labels
+    # @param freeform [String, nil]
+    # @return [Hash] normalized answer
+    def answer(id:, selected:, freeform: nil)
+      sel = Array(selected).map { |v| v.to_s.strip }.reject(&:empty?)
+      fm = freeform.to_s.strip
+      fm = nil if fm.empty?
+      @lock.synchronize do
+        pending = @pending
+        raise NotPending, "no pending question" unless pending
+        raise NotPending, "id mismatch" unless pending[:id].to_s == id.to_s
+        # First responder wins: after the first answer the turn thread clears
+        # @pending in a later lock block, so a second UI's answer can
+        # land in between and must not overwrite the first.
+        raise NotPending, "question already answered" if @answer
+        raise NotPending, "question #{pending[:status]}" unless pending[:status].to_s == "pending"
+
+        opts = Array(pending[:options])
+        # Validate selected subset of options (value == label in v1)
+        invalid = sel.reject { |v| opts.include?(v) }
+        unless invalid.empty?
+          raise ArgumentError, "invalid selection: #{invalid.join(', ')} (valid: #{opts.join(', ')})"
+        end
+        if !pending[:multi_select] && sel.size > 1
+          raise ArgumentError, "single-select question: got #{sel.size} selections"
+        end
+        if pending[:multi_select] == false && sel.empty? && fm.nil?
+          raise ArgumentError, "selection required"
+        end
+        # Persist pending cleared elsewhere; just set answer
+        answer = { id: id.to_s, selected: sel, freeform: fm }
+        # Derive indices for convenience
+        answer[:selected_indices] = sel.map { |v| opts.index(v) }.compact
+        @answer = answer
+        @cv.broadcast
+        answer
+      end.tap do
+        # A human answered: the session is back in the lists (ArchiveStore).
+        @user_input.call(session&.id)
+      end
+    end
+
+    def sync_handler=(block)
+      @sync_handler = block
+    end
+
+    # Cancel the pending question (e.g. /cancel, a dismiss). Announces which
+    # one, so every UI closes it; with none pending there is nothing to
+    # announce. A question already answered (the turn thread hasn't taken the
+    # answer yet) or already closed stays as it is: the first responder wins.
+    # @param id [String, nil] cancel only this question (a UI's dismiss
+    #   names the one it showed)
+    # @return [Boolean] whether it was cancelled (true with none pending and
+    #   no id, as before)
+    def cancel(reason = "user", id: nil)
+      cancelled_id = @lock.synchronize do
+        pending = @pending
+        next unless pending
+        next if id && pending[:id].to_s != id.to_s
+        next if @answer || pending[:status].to_s != "pending"
+
+        pending[:status] = "cancelled"
+        @cv.broadcast
+        pending[:id]
+      end
+      return id.nil? && self.pending.nil? unless cancelled_id
+
+      emit({ type: :question_cancelled, id: cancelled_id, reason: reason.to_s }) rescue nil
+      true
+    end
+
+    # A question through the question flow (REPL sync handler, attached TUI,
+    # web), single-select, kind "hook". A --non-interactive run has no one
+    # to ask: nil at once. Anything but an answer (a sync handler's text, no
+    # answer, cancelled) is nil too.
+    # @return [Hash, nil] {selected:, freeform:, selected_indices:}
+    def ask_for_hook(question, options, header, allow_freeform, hook)
+      return nil if @interface_lookup.call == :non_interactive
+
+      opts = Tools::AskUserQuestion.normalize_options(options)
+      unless opts
+        Log.warn(:hooks, "ask_user_invalid", echo: "[samagotchi:hooks] #{hook} asked with invalid options (2-8 strings)", hook: hook.to_s)
+        return nil
+      end
+
+      fields = { question: question.to_s, options: opts, header: header, multi_select: false,
+                 allow_freeform: !!allow_freeform, kind: "hook", hook: hook.to_s }.compact
+      answer = open_question(fields)
+      return nil unless answer.is_a?(Hash) && answer[:selected]
+
+      result = { selected: Array(answer[:selected]), freeform: answer[:freeform] }
+      result[:selected_indices] = answer[:selected_indices] if answer.key?(:selected_indices)
+      result
+    end
+
+    private
+
+    def session = @session_lookup.call
+    def state_dir = @state_dir_lookup.call
+    def cancel_controller = @cancel_controller_lookup.call
+    def emit(event) = @emit.call(event)
+
+    # The session file no longer holds a pending question.
+    def clear_saved_question
+      return unless session
+
+      session.pending_question = nil
+      begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
+    end
+  end
+end