samagotchi 0.153.0 → 0.154.1

data/lib/samagotchi/engine/cards.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # Cards and anytime commands: #show_card (routed by EventRoutes), the
+    # anytime and session-command thread marks, the anytime threads #shutdown
+    # waits for. Reads @event_routes, @anytime_threads under @lifecycle_mutex.
+    module CardsPart
+      # ── Cards ───────────────────────────────────────────────────────────────
+
+      # Show a card in every UI (docs/plugins.md, Cards): {type: :card, id:,
+      # source:, title:, body:, level:, actions: [{label:, command:}], in_turn:}.
+      # Where it goes (held while the plugins load, an anytime command's, an
+      # init task's, a turn event, else announced) is EventRoutes#route's,
+      # marked in_turn: (CARD_MARKS). A card with the id of an earlier one
+      # replaces it (btw's "thinking…" → the answer).
+      # @param source [String] who shows it (a bundle's name)
+      # @param actions [Array<Hash>] {label:, command:}; a command is a line
+      #   the session runs, as typed (D3)
+      # @return [String] the card's id
+      # @raise [ArgumentError] a card without a title, or a bad action
+      def show_card(source:, title:, body: "", actions: [], level: :info, id: nil)
+        card = Plugin::Card.build(source: source, title: title, body: body, actions: actions, level: level, id: id)
+        command = Thread.current[running_command_key]
+        card[:command] = command if command
+        @event_routes.route(card, **EventRoutes::CARD_MARKS)
+        card[:id]
+      end
+
+      # Run an anytime command's block (D8): the cards and notices it shows on
+      # this thread are announced at once, marked anytime: true, and are
+      # never a running turn's events. They belong to the command, not the
+      # turn, and a UI shows them after the command's own line (a web
+      # command bubble drawn at its command_queued), even mid-turn.
+      # @return the block's value
+      def running_anytime
+        key = :"samagotchi_anytime_#{object_id}"
+        outer = Thread.current[key]
+        Thread.current[key] = true
+        yield
+      ensure
+        Thread.current[key] = outer
+      end
+
+      # Run a session command's dispatch: a card shown on this thread says
+      # it's that command's (:card's command:), for a reload that no longer has
+      # the command's line above it (Bridge::CardStore). A thread of its own
+      # isn't the command, nor a card shown after it.
+      # @param name [String] the command, "/short"
+      # @return the block's value
+      def running_command(name)
+        outer = Thread.current[running_command_key]
+        Thread.current[running_command_key] = name
+        yield
+      ensure
+        Thread.current[running_command_key] = outer
+      end
+
+      # Whether an anytime command (/btw) still runs on its thread.
+      def anytime_running?
+        @lifecycle_mutex.synchronize { @anytime_threads.any?(&:alive?) }
+      end
+
+      # Start an anytime command on its own thread (D8), one #shutdown waits
+      # for, so its command_ran is announced before the process leaves.
+      # @return [Thread]
+      def spawn_anytime(&)
+        thread = Thread.new(&)
+        @lifecycle_mutex.synchronize do
+          @anytime_threads.select!(&:alive?)
+          @anytime_threads << thread
+        end
+        thread
+      end
+
+      def anytime_thread? = Thread.current[:"samagotchi_anytime_#{object_id}"] == true
+      private :anytime_thread?
+
+      def announce_anytime(event)
+        event = event.merge(anytime: true)
+        announce(event)
+        event
+      end
+      private :announce_anytime
+    end
+  end
+end

data/lib/samagotchi/engine/context_judge.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The attached-context candidate judge (ContextJudge): its pass at an
+    # owner turn's start and for a late candidate, the asks it starts, and
+    # the cards it shows after the turn. Reads @context_cards_after_turn
+    # under @context_cards_mutex, @side_judgments, @host_registry, @session.
+    module ContextJudgePart
+      private
+
+      # The candidate judge (ContextJudge) at an owner turn's start, after
+      # the toolkit's ask settled: the session's candidates' status changes
+      # are logged (ContextCandidatesLog#look) and, unless
+      # context.candidates.mode is off, the proposed candidates due an ask
+      # are asked about the owner's prompts so far, this one included. Never
+      # a participant's turn, a review session or a Continue (no new prompt).
+      def start_context_judge(turn)
+        session = turn.session
+        return unless turn.prompt.is_a?(String) && OwnerPrompt.turn?(session: session, author: turn.origin.author)
+
+        context_judge_pass(session, ContextCandidates.owner_texts(session.messages) + [turn.prompt], phase: "turn")
+      end
+      private :start_context_judge
+
+      # A late proposal no owner prompt mentions (Plugin::Host
+      # #candidate_proposed: github-pr's init task runs beside the first
+      # turn): judged on the owner's prompts so far, the running turn's too.
+      def judge_late_candidates
+        session = @session
+        return if session.nil? || session.review?
+
+        texts = ContextCandidates.owner_texts(plugin_messages)
+        context_judge_pass(session, texts, phase: "late") unless texts.empty?
+      end
+      private :judge_late_candidates
+
+      # One look at +session+'s candidates; the asks go to SideJudgments'
+      # :context kind, one thread asking each due candidate in turn.
+      def context_judge_pass(session, texts, phase:)
+        return if session.id.nil? || session.scratch
+
+        rows = ContextCandidates.with_status(session.id, project_root: session.project_root, state_dir: session_state_dir)
+        return if rows.empty?
+
+        log = ContextCandidatesLog.log_for(session_state_dir)
+        records = ContextCandidatesLog.records_for(log, session.id)
+        ContextCandidatesLog.look(log, session.id, rows, records) if phase == "turn"
+        settings = ContextJudge::Settings.from_config
+        return if settings.mode == "off"
+
+        jobs = ContextJudge.jobs(rows, records, session_id: session.id, texts: texts, settings: settings, phase: phase,
+                                                parent_attached: context_parent_attached(session))
+        return if jobs.empty?
+
+        client = system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :context),
+                                      ContextJudge::JUDGMENT, session, mode: settings.mode)
+        return unless client
+
+        start_context_asks(client, jobs, log, settings, context_choice(session, log, settings))
+      rescue StandardError => e
+        ContextJudge.warn(e)
+      end
+      private :context_judge_pass
+
+      # @return [Thread, nil] the asks' thread, nil when none started
+      def start_context_asks(client, jobs, log, settings, choice)
+        if @side_judgments.in_flight?(:context)
+          Log.info(:context, "context_judge_in_flight_skipped", session_id: jobs.first.session_id)
+          return nil
+        end
+
+        @side_judgments.start(:context, warn: ContextJudge.method(:warn)) do
+          jobs.each { |job| choice.call(job, ContextJudge.ask(client: client, job: job, log: log, settings: settings)) }
+        end
+      end
+      private :start_context_asks
+
+      # What an answer does on the asks' thread (ContextCandidateChoice
+      # #after_judged: on mode attaches or cards; audit nothing). Taken on
+      # the caller's thread. The attach only writes the session's folder: its
+      # note comes with the next between-turn delivery, never into a running
+      # turn. A card shows only while this Engine is still on that session,
+      # and not in a running turn (it isn't the turn's: no "waiting for you"
+      # on it), but once it has ended.
+      # @return [#call] (job, fields)
+      def context_choice(session, log, settings)
+        session_id = session.id
+        project_root = session.project_root
+        state_dir = session_state_dir
+        show = lambda do |**card|
+          current = @session
+          next nil unless current.nil? || current.id == session_id
+
+          @context_cards_mutex.synchronize do
+            next @context_cards_after_turn << card if turn_running?
+
+            show_card(**card)
+          end
+        end
+        lambda do |job, fields|
+          ContextCandidateChoice.after_judged(job: job, fields: fields, settings: settings, project_root: project_root,
+                                              state_dir: state_dir, log: log, show_card: show)
+        end
+      end
+      private :context_choice
+
+      # The cards #context_choice held while a turn ran (#run_turn's ensure,
+      # after the turn flag is released).
+      def show_context_cards_after_turn
+        cards = @context_cards_mutex.synchronize { @context_cards_after_turn.slice!(0..) }
+        cards.each { |card| show_card(**card) }
+      rescue StandardError => e
+        ContextJudge.warn(e)
+      end
+      private :show_context_cards_after_turn
+
+      # A delegate child's parent's sources, by title (else name): the
+      # judge's started_from. nil for any other session (a chi send --new
+      # session has no parent; a fork isn't a delegate).
+      def context_parent_attached(session)
+        return nil unless session.delegate? && session.parent_id
+
+        parent_root = if Session.exist?(session.parent_id, state_dir: session_state_dir)
+                        Session.load(session.parent_id, state_dir: session_state_dir).project_root
+                      else
+                        session.project_root
+                      end
+        ContextSources.attached(session.parent_id, project_root: parent_root, state_dir: session_state_dir)
+                      .map { |attached| attached.source.title || attached.name }
+      rescue StandardError => e
+        Log.warn(:context, "context_parent_attached_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        []
+      end
+      private :context_parent_attached
+    end
+  end
+end

data/lib/samagotchi/engine/events.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The event log: persistent observers, #announce (ANNOUNCEABLE_EVENTS),
+    # the event lock, held announcements, the load events, and the stream
+    # and emit helpers (EventFanout's, forwarded). Writes
+    # @guardrail_failures_announced; reads @session_observer, @event_fanout,
+    # @extension_load, @guardrail_failures, @plugin_failures.
+    module EventsPart
+      # Subscribe a persistent observer to engine events.
+      #
+      # Unlike the turn-scoped `on_event:` sink, a subscribed observer keeps
+      # receiving events across every `run_turn` call on this Engine. Each
+      # delivery carries a locally-monotonic `event_seq`. The returned handle can
+      # be used to unsubscribe later.
+      # @param observer [#call] receives event hashes (with `event_seq:` merged in)
+      # @return [Samagotchi::SessionObserver::SubscribedObserver] handle to unsubscribe
+      def subscribe(observer:)
+        @session_observer.subscribe(observer: observer)
+      end
+
+      # Unsubscribe a previously-registered observer.
+      # @param handle [Samagotchi::SessionObserver::SubscribedObserver]
+      # @return [Boolean] whether the observer was removed (nil/unknown never raises)
+      def unsubscribe(handle:)
+        @session_observer.unsubscribe(handle: handle)
+      end
+
+      # @return [Integer] total engine events emitted so far (locally monotonic)
+      def event_count
+        @session_observer.event_count
+      end
+
+      # Put a transport-level event into the ordered event log. Unlike turn
+      # events it reaches only persistent observers (no turn sink, no memory
+      # capture).
+      # @param event [Hash] with :type in ANNOUNCEABLE_EVENTS
+      # @raise [ArgumentError] for any other type
+      def announce(event)
+        unless ANNOUNCEABLE_EVENTS.include?(event[:type])
+          raise ArgumentError, "cannot announce #{event[:type].inspect} (allowed: #{ANNOUNCEABLE_EVENTS.join(", ")})"
+        end
+
+        @session_observer.notify(event)
+      end
+
+      # Run the block with the event log held: no event is numbered or
+      # delivered meanwhile, and events the block emits keep their order.
+      def synchronize_events(&)
+        @session_observer.synchronize(&)
+      end
+
+      # The working set's :working_set_updated, announced between turns
+      # (after a command changed what the next request sends), when it
+      # differs from the last one emitted (#emit_working_set). Under the
+      # event lock, so it is ordered with the change's own events.
+      def announce_working_set(session = @session)
+        return unless session
+
+        synchronize_events { emit_working_set(nil, session, session.messages) }
+      end
+
+      # ── Load events ───────────────────────────────────────────────────────
+
+      # Announce what failed to load and what plugins showed while loading,
+      # once, as soon as the owner can show it (the worker's Bridge is up):
+      # the guardrail and plugin warnings, an orphaned
+      # project memory folder (label: "memory", MemoryOrphans), then the
+      # held notices (between_turns) and cards (in_turn: false, so late
+      # joiners get them). Without this call the first turn announces them
+      # (#announce_guardrail_failures).
+      def announce_load_events!
+        synchronize_events do
+          next if @guardrail_failures_announced
+
+          @guardrail_failures_announced = true
+          message = @guardrail_failures.message
+          announce({ type: :guardrail_warning, message: message }) if message
+          plugins = @plugin_failures.message
+          announce({ type: :guardrail_warning, message: plugins, label: "plugins" }) if plugins
+          memory = MemoryOrphans.message
+          announce({ type: :guardrail_warning, message: memory, label: "memory" }) if memory
+          @extension_load.held_events.each do |event|
+            announce(event[:type] == :card ? event.merge(in_turn: false) : event.merge(between_turns: true))
+          end
+        end
+        nil
+      end
+
+      # Run the block holding back the cards and between-turns notices it
+      # announces on this thread, so the caller announces them after its own
+      # event (a worker's command: its command_ran first, so a UI prints the
+      # command's output before its cards).
+      # @return [Array(Object, Array<Hash>)] the block's value and the held events
+      def holding_announcements
+        key = :"samagotchi_held_#{object_id}"
+        outer = Thread.current[key]
+        Thread.current[key] = []
+        value = yield
+        [value, Thread.current[key]]
+      ensure
+        Thread.current[key] = outer
+      end
+
+      # Announce +event+ now, or keep it for #holding_announcements' caller.
+      def announce_or_hold(event)
+        held = Thread.current[:"samagotchi_held_#{object_id}"]
+        held ? held << event : announce(event)
+      end
+      private :announce_or_hold
+
+      private
+
+      # ── Event helpers ──────────────────────────────────────────────────────────
+
+      # The stream handler, the working set and the event fan-out are
+      # EventFanout's (#build_event_fanout); these forward to it.
+      def build_stream_event_handler(...) = @event_fanout.build_stream_event_handler(...)
+      def emit_working_set(...) = @event_fanout.emit_working_set(...)
+      private :emit_working_set
+      def working_set_llm_context = @event_fanout.working_set_llm_context
+      private :working_set_llm_context
+      def with_generation_report(event) = @event_fanout.with_generation_report(event)
+      private :with_generation_report
+      def stream_watch(cancel_controller) = @event_fanout.stream_watch(cancel_controller)
+      private :stream_watch
+      def emit_event(on_event, event) = @event_fanout.emit_event(on_event, event)
+    end
+  end
+end

data/lib/samagotchi/engine/guardrails.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The tool guardrails (GuardrailWiring, forwarded): who answers an
+    # approval, the rules and approvals, their state dir, and the load
+    # warnings the first turn announces. Writes @state_dir,
+    # @guardrail_failures_announced; reads @guardrail_wiring,
+    # @guardrail_failures, @plugin_failures, @hook_routes.
+    module GuardrailsPart
+      # ── Guardrails ─────────────────────────────────────────────────────────────
+
+      # Who can answer an approval: :worker or :non_interactive (the
+      # default, so a bare Engine denies instead of waiting for nobody). Set
+      # by the host (TerminalUI, Worker).
+      def interface
+        @guardrail_wiring.interface
+      end
+
+      def interface=(value)
+        @guardrail_wiring.interface = value
+      end
+
+      def guardrail_state_dir=(state_dir)
+        # Also where list_sessions and send_note look for other sessions.
+        @state_dir = state_dir
+        @guardrail_wiring.state_dir = state_dir
+      end
+
+      # The YAML rules, read again when a file changed (GuardrailWiring#rules).
+      # @return [Guardrails::Rules]
+      def guardrail_rules
+        @guardrail_wiring.rules
+      end
+
+      # @return [Guardrails::LoadFailures]
+      attr_reader :guardrail_failures
+
+      # @return [Guardrails::Approvals]
+      def guardrail_approvals
+        @guardrail_wiring.approvals
+      end
+
+      # @return [Guardrails::LoadFailures] the plugins that failed to load
+      attr_reader :plugin_failures
+
+      # Once per Engine, on its first turn: what failed to load, so every UI
+      # (the attached TUI, the web, a one-shot's stderr) shows it: the guardrails, then the plugins
+      # (label: "plugins"; the UIs say guardrails without one), an orphaned
+      # project memory folder (label: "memory"), then the notices and cards plugins showed as they loaded.
+      def announce_guardrail_failures(on_event)
+        return if @guardrail_failures_announced
+
+        @guardrail_failures_announced = true
+        message = @guardrail_failures.message
+        emit_event(on_event, { type: :guardrail_warning, message: message }) if message
+        plugins = @plugin_failures.message
+        emit_event(on_event, { type: :guardrail_warning, message: plugins, label: "plugins" }) if plugins
+        memory = MemoryOrphans.message
+        emit_event(on_event, { type: :guardrail_warning, message: memory, label: "memory" }) if memory
+        @extension_load.held_events.each { |event| emit_event(on_event, event) }
+      end
+      private :announce_guardrail_failures
+
+      # The warning the first turn announced (nil before it, or with nothing
+      # failed), for a UI that joins later (Bridge#snapshot).
+      def guardrail_warning
+        @guardrail_failures.message if @guardrail_failures_announced
+      end
+
+      # The plugins' load warning the first turn announced, likewise, and what
+      # their failed chi.on handlers told (HookRoutes#plugin_hook_failed).
+      def plugin_warning
+        loaded = @plugin_failures.message if @guardrail_failures_announced
+        [loaded, @hook_routes.hook_failures_message].compact.join("; ").then { |text| text unless text.empty? }
+      end
+
+      # Ask the user to approve a call the gate voted `ask` on
+      # (GuardrailWiring#request_approval).
+      # @param verdict [Guardrails::Verdict]
+      # @return [Guardrails::Verdict]
+      def request_approval(verdict)
+        @guardrail_wiring.request_approval(verdict)
+      end
+    end
+  end
+end

data/lib/samagotchi/engine/hooks.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # Hooks and reminders: turn-scoped hooks (register, clear), the hook
+    # runtime's notify/ask/stop (HookRoutes, forwarded), the copy of the
+    # conversation a hook reads, and the due reminders. Reads @hooks,
+    # @hook_routes, @reminder_queue, @reminder_store.
+    module HooksPart
+      # @return [Array<String>] reminder names queued for a reminder turn
+      def due_reminder_names
+        @reminder_queue.pending_names
+      end
+
+      # Queue reminder names for a reminder turn (IdleReminders callback).
+      def note_due_reminders(names)
+        @reminder_queue.note_pending(names)
+      end
+
+      def clear_due_reminder_names!
+        @reminder_queue.clear_pending!
+      end
+
+      # ── Hooks API ──────────────────────────────────────────────────────────────
+
+      # Register a hook callback for a named lifecycle event.
+      #
+      # Hooks are turn-scoped: they are automatically cleared after each
+      # `run_turn` call so that a single turn's hooks do not leak into the next.
+      #
+      # A hook that raises tells the user once, as a bundle's does
+      # (HookRoutes#plugin_hook_failed); the registry logs each failure and goes on.
+      #
+      # @param name [Symbol] one of the hook names (see Hooks module)
+      # @param block [Proc] receives an event hash (may mutate in place)
+      # @return [void]
+      def register_hook(name, &block)
+        return @hooks.register(name) unless block
+
+        @hooks.register(name) do |event|
+          yield(event)
+        rescue StandardError => e
+          @hook_routes.plugin_hook_failed("#{Hooks::Registry::TURN_HOOK_LABEL} (#{name})", "#{e.class}: #{e.message}")
+          raise
+        end
+      end
+
+      # Unregister a previously registered hook.
+      # @param name [Symbol]
+      # @return [Boolean] true if it was removed, false if not found
+      def unregister_hook(name)
+        @hooks.unregister(name)
+      end
+
+      # Clear all registered hooks. Called automatically at the end of each
+      # `run_turn` to keep hooks turn-scoped.
+      # @return [void]
+      def clear_hooks
+        @hooks.clear_all
+      end
+
+      # ── Reminders API ────────────────────────────────────────────────────────────
+      #
+      # Each turn injects the reminders due then (#turn_messages,
+      # ReminderQueue#inject!). Between turns the idle tick (IdleReminders)
+      # finds them due and its callback queues their names
+      # (#note_due_reminders); the worker runs a reminder turn
+      # (a continue turn) for them.
+
+      # @return [Boolean] whether any reminder is due now (the store's view,
+      #   which a turn would inject), regardless of the queued names
+      def reminders_due?
+        @reminder_queue.due?
+      end
+
+      # @return [ReminderStore] the reminder store for inspection
+      attr_reader :reminder_store
+
+      # The conversation as a hook may read it: a frozen array of copied
+      # messages, so a hook cannot change what the turn sends or stores.
+      def hook_messages(messages)
+        AnswerDisplay.strip_all(messages).map(&:dup).freeze
+      end
+      private :hook_messages
+
+      # ── The hook runtime (HookRoutes) ───────────────────────────────────────
+
+      # What a hook (Hooks::Runtime) and a plugin (Plugin::Host) can do beyond
+      # reading its event, routed to the UIs by HookRoutes; these forward.
+      def hook_runtime = @hook_routes.runtime
+      private :hook_runtime
+
+      def hook_source(hook) = @hook_routes.source(hook)
+      private :hook_source
+
+      # One line to the user (:hook_notice), HookRoutes#notify.
+      def hook_notify(text, level, hook, fallback_for: nil, extra: {})
+        @hook_routes.notify(text, level, hook, fallback_for: fallback_for, extra: extra)
+      end
+      private :hook_notify
+
+      def guardrail_notify(message) = @hook_routes.guardrail_notify(message)
+      private :guardrail_notify
+
+      # @param question [HookQuestion]
+      # @return [Hash, nil] {selected:, freeform:, selected_indices:}
+      def hook_ask_user(question) = @hook_routes.ask_user(question)
+      private :hook_ask_user
+
+      # @return [Boolean] true when a running turn was cancelled now
+      def hook_stop_turn(reason, hook) = @hook_routes.stop_turn(reason, hook)
+      private :hook_stop_turn
+
+      # @return [Boolean] true when a streaming generation was cut now
+      def hook_stop_generation(reason, hook) = @hook_routes.stop_generation(reason, hook)
+      private :hook_stop_generation
+    end
+  end
+end