samagotchi 0.152.0 → 0.154.0

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

data/lib/samagotchi/engine/messages.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The session messages API: out-of-turn edits to the current session's
+    # conversation (replace, append, a context note, rollback), its
+    # checkpoints and last answer, and the running turn's live conversation.
+    # Reads @session and @kernel; every edit goes through
+    # #replace_session_messages.
+    module MessagesPart
+      # The strategy the working set is built under now, as LLMContextView
+      # takes it: the running turn's, else the next turn's (#emit_working_set).
+      # /working-set's ops act under it.
+      # @return [Symbol, Array<Symbol>]
+      def working_set_strategy
+        working_set_llm_context&.strategy || LLMContextView::NONE
+      end
+
+      # Replace the current session's conversation, between turns (a
+      # /working-set op's copy: #clone_messages, then its edits).
+      # @param messages [Array<Hash>]
+      # @return [Array<Hash>] the session's messages
+      def replace_messages(messages)
+        raise ArgumentError, "no current session" unless @session
+
+        replace_session_messages(@session, messages)
+      end
+
+      # Add a context note to the session's conversation, between turns: a
+      # tail system message the next turn sees, announced as :context_added.
+      # The array is replaced, not mutated, and the append and the event
+      # happen under the event lock, so a joining UI sees both or neither.
+      # The caller saves the session.
+      # @param note [Hash] SessionInbox.read_note's shape
+      # @return [Hash, nil] the message, or nil when the conversation already
+      #   holds this note (a note file re-read after a crash)
+      def add_context_note(session, note)
+        synchronize_events do
+          next nil if Array(session.messages).any? { |m| m[:note_id] == note[:note_id] }
+
+          message = ContextNote.message(**note)
+          entry = note[:objectives] && Objectives.entry(note[:objectives], before: Objectives.build(session.messages))
+          replace_session_messages(session, Array(session.messages) + [message])
+          announce({ type: :context_added, session_id: session.id, note_id: note[:note_id], source: note[:source],
+                     label: ContextNote.label_of(message), from_session: note[:from_session],
+                     from_cwd: note[:from_cwd], text: note[:text], context_source: note[:context_source],
+                     created_at: note[:created_at], objectives: entry }.compact)
+          announce_objectives(session) if entry
+          objectives_audit.note(session, note)
+          message
+        end
+      end
+
+      # ── Session messages API ───────────────────────────────────────────────
+      #
+      # Out-of-turn edits to the current session's conversation (`!cmd` output,
+      # rollback after Ctrl-C). Each replaces the array rather than mutating it,
+      # so the recap's lock-free snapshot never sees a half-applied edit.
+
+      # The answer a UI shows last (AnswerTail), a copy of that one message
+      # only: walked back from the end, never a #messages_checkpoint of the
+      # whole conversation (the Bridge's GET tail). +turn_id+: that turn's
+      # answer (AnswerTail.find); unknown or nil: the newest.
+      # @return [Hash, nil]
+      def last_answer_message(turn_id: nil)
+        AnswerTail.find(@session&.messages, turn_id: turn_id)&.dup
+      end
+
+      # @return [Array<Hash>] a copy of the current session's messages to hand
+      #   back to #rollback_to later
+      def messages_checkpoint
+        clone_messages(@session&.messages)
+      end
+
+      # The running turn's conversation as its loop builds it (both loops
+      # register it on the kernel's llm_context_turn): the same array the loop
+      # appends to, not a copy, so read it on the turn's thread (the pending
+      # input drain, at an iteration boundary: TurnCheckpoint), or from another
+      # only as a dup, read only (/objectives). nil when no
+      # turn runs (llm_context_turn is never cleared, and still holds the
+      # last turn's then).
+      # @return [Array<Hash>, nil]
+      def live_conversation
+        return nil unless turn_running? && @kernel.respond_to?(:llm_context_turn)
+
+        @kernel.llm_context_turn&.conversation
+      end
+
+      # Append messages to the current session's conversation.
+      # @param messages [Array<Hash>]
+      # @return [Array<Hash>] the session's messages
+      def append_messages(messages)
+        raise ArgumentError, "no current session" unless @session
+
+        replace_session_messages(@session, Array(@session.messages) + clone_messages(messages))
+      end
+
+      # Restore the current session's conversation to a #messages_checkpoint.
+      # Between turns the working set is announced when that changed it (a
+      # !rollback or a canceled continue dropping the turn's tool calls, the
+      # set emptied too), so the page doesn't keep the dropped items until
+      # the next request.
+      # @param checkpoint [Array<Hash>]
+      # @return [Array<Hash>] the session's messages
+      def rollback_to(checkpoint)
+        raise ArgumentError, "no current session" unless @session
+
+        messages = replace_session_messages(@session, clone_messages(checkpoint))
+        unless turn_running?
+          announce_working_set
+          announce_objectives
+        end
+        messages
+      end
+
+      # Clone a messages array (shallow dup of each element).
+      # @param messages [Array<Hash>]
+      # @return [Array<Hash>]
+      def clone_messages(messages)
+        Array(messages).map(&:dup)
+      end
+    end
+  end
+end

data/lib/samagotchi/engine/model_settings.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The session's settings on its effective model (SessionModelSettings) and
+    # the UIs' snapshots (EngineSnapshots), forwarded: /model's and /stats'
+    # summaries, the overrides a session saves, what a turn reads. Writes
+    # @last_context_status; reads @model_settings, @engine_snapshots, @metrics.
+    module ModelSettingsPart
+      # The metrics for /stats, which may make one short /props GET
+      # (EngineSnapshots#stats_snapshot).
+      # @return [Hash] @metrics.snapshot, filled in
+      def stats_snapshot = @engine_snapshots.stats_snapshot
+
+      # ── The session's model settings (SessionModelSettings) ──────────────────
+
+      # The session's own thinking, reasoning_history and llm_context values
+      # over the effective model's, the summaries /model and /stats show, and
+      # the saved context's status: SessionModelSettings' (resolved on every
+      # read); these forward.
+      def saved_context_status(context, model: :current) = @model_settings.saved_context_status(context, model: model)
+      def llm_context_explained(own: :session) = @model_settings.llm_context_explained(own: own)
+      def llm_context_summary = @model_settings.llm_context_summary
+      def llm_context_override = @model_settings.llm_context_override
+      def chat_model? = @model_settings.chat_model?
+      def sampling_summary = @model_settings.sampling_summary
+      def thinking_summary = @model_settings.thinking_summary
+      def steer_cut_after_explained = @model_settings.steer_cut_after_explained
+      def steer_cut_after = @model_settings.steer_cut_after
+      def steer_cut_summary = @model_settings.steer_cut_summary
+      def thinking_explained(own: thinking_override) = @model_settings.thinking_explained(own: own)
+      def reasoning_history_summary = @model_settings.reasoning_history_summary
+      def reasoning_history_cache_cost(from, to) = @model_settings.reasoning_history_cache_cost(from, to)
+      def reasoning_history_override = @model_settings.reasoning_history_override
+      def thinking_override = @model_settings.thinking_override
+      def served_expected_by(served) = @model_settings.served_expected_by(served)
+      def served_expected?(served) = @model_settings.served_expected?(served)
+
+      def reasoning_history_explained(native: false, own: reasoning_history_override)
+        @model_settings.reasoning_history_explained(native: native, own: own)
+      end
+
+      # Set the session's own reasoning_history or thinking level (nil unsets
+      # it): SessionModelSettings'. The caller saves the session.
+      # @raise [ArgumentError] with no session yet
+      def reasoning_history_override=(level)
+        @model_settings.reasoning_history_override = level
+      end
+
+      def thinking_override=(level)
+        @model_settings.thinking_override = level
+      end
+
+      # Set the session's own llm_context values (an empty override unsets
+      # them); the next turn's start resolves them, never a running one (its
+      # TurnSettings are fixed). The caller saves the session.
+      # @raise [ArgumentError] with no session yet
+      def llm_context_override=(override)
+        raise ArgumentError, "no session yet" unless @session
+
+        SessionSetting::LLM_CONTEXT.set(@session, override)
+        # The status a later client reads counts against the new budget.
+        @last_context_status = saved_context_status(@metrics.snapshot[:context]) || @last_context_status if @last_context_status
+      end
+
+      # Whether the session has a model reply (a cache to restart at all).
+      def history?
+        Array(@session&.messages).any? { |entry| entry[:role].to_s == "model" }
+      end
+
+      # The latest known context size used by a request, for a cache-restart
+      # confirmation; nil before any request reports a count.
+      # @return [Integer, nil]
+      def cache_restart_tokens
+        used = @metrics.snapshot.dig(:context, :used_tokens)
+        used if used.is_a?(Integer)
+      end
+
+      # Whether a cache restart can invalidate preserved thinking blocks.
+      def cache_restart_anthropic?
+        effective_model.entry&.api.to_s == "anthropic"
+      end
+
+      # What a thinking level change costs the effective model's prompt
+      # cache (Thinking.cache_cost): :full, :provider or :tail.
+      # @return [Symbol]
+      def thinking_cache_cost
+        effective_model.thinking_cache_cost { profile }
+      end
+
+      # The model the server serves for the current model, and the name asked
+      # for: what the last generation of that name reported, else llama.cpp's
+      # model_alias (/props, one short cached probe; not with probe: false),
+      # else [nil, nil].
+      # @return [Array(String, String), Array(nil, nil)]
+      def served_model(probe: true)
+        @engine_snapshots.served_model_for(@metrics.served_report, model: probe ? effective_model : nil)
+      end
+
+      # Read-only snapshot of the engine's view of the current session plus the
+      # live event sequence; cheap, never probes, never raises
+      # (EngineSnapshots#session_state_snapshot has its keys).
+      # @return [Hash]
+      def session_state_snapshot = @engine_snapshots.session_state_snapshot
+
+      # The effective model's sampling and thinking level as the next turn
+      # reads them (SessionModelSettings).
+      def turn_sampling = @model_settings.turn_sampling
+      def turn_thinking = @model_settings.turn_thinking
+
+      private
+
+      # The effective model's window_tokens and price, read per turn
+      # (SessionModelSettings).
+      def turn_window_setting = @model_settings.turn_window_setting
+      def turn_price = @model_settings.turn_price
+
+      # The snapshots' helpers are EngineSnapshots' (#build_engine_snapshots);
+      # these forward to it.
+      def served_model_for(...) = @engine_snapshots.served_model_for(...)
+      def kit_prompt_stats = @engine_snapshots.kit_prompt_stats
+
+      # +settings+' chips (EngineSnapshots#setting_chips).
+      def setting_chips(settings, model) = @engine_snapshots.setting_chips(settings, model)
+    end
+  end
+end