samagotchi 0.65.0 → 0.67.0

data/lib/samagotchi/hook_routes.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "hooks"
+require_relative "log"
+
+module Samagotchi
+  # The Engine's routes to the UIs for what a hook or a plugin does beyond
+  # reading its event (Hooks::Runtime, Plugin::Host): a notice (#notify),
+  # a question (#ask_user), stopping the turn or cutting its generation,
+  # and a steer; also the guardrails' line after load (#guardrail_notify).
+  #
+  # What it needs from the Engine comes through lookups, called at use.
+  class HookRoutes
+    # What a notice may stand in for (#notify's fallback_for:).
+    NOTICE_FALLBACKS = %i[display editor].freeze
+
+    # @param extension_load    [#call] → ExtensionLoad (#loading?, #hold)
+    # @param in_turn_sink      [#call] → [Boolean, sink] (TurnState#in_turn_sink)
+    # @param anytime_thread    [#call] → whether this thread runs an anytime command
+    # @param announce_anytime  [#call] (event) → announces an anytime command's event
+    # @param init_task         [#call] → the init task running on this thread, nil
+    # @param announce          [#call] (event) → announces an event
+    # @param announce_or_hold  [#call] (event) → announces it, or holds it for the caller
+    # @param emit              [#call] (sink, event) → emits to a turn's sink + observers
+    # @param question_desk     [#call] → QuestionDesk
+    # @param cancel_controller [#call] → the running turn's CancellationController, nil
+    # @param steer             [#call] (text, source) → steers the running turn
+    def initialize(extension_load:, in_turn_sink:, anytime_thread:, announce_anytime:, init_task:, announce:,
+                   announce_or_hold:, emit:, question_desk:, cancel_controller:, steer:)
+      @extension_load = extension_load
+      @in_turn_sink = in_turn_sink
+      @anytime_thread = anytime_thread
+      @announce_anytime = announce_anytime
+      @init_task = init_task
+      @announce = announce
+      @announce_or_hold = announce_or_hold
+      @emit = emit
+      @question_desk = question_desk
+      @cancel_controller = cancel_controller
+      @steer = steer
+      @unknown_fallbacks = Set.new
+    end
+
+    # The things a hook can do beyond reading its event. Each gets the
+    # hook's label (event[:hook]) from the registry.
+    # @return [Hooks::Runtime]
+    def runtime
+      Hooks::Runtime.new(
+        notify: ->(text:, level:, hook:, fallback_for: nil) { notify(text, level, hook, fallback_for: fallback_for) },
+        ask_user: ->(question:, options:, header:, allow_freeform:, hook:) { ask_user(question, options, header, allow_freeform, hook) },
+        stop_turn: ->(reason:, hook:) { stop_turn(reason, hook) },
+        steer: ->(text:, hook:) { @steer.call(text, source(hook)) },
+        stop_generation: ->(reason:, hook:) { stop_generation(reason, hook) }
+      )
+    end
+
+    # What a steer is attributed to: the bundle of a bundle hook's label
+    # ("<file> (bundle <name>)"), the label of any other.
+    def source(hook)
+      hook.to_s[/\(bundle (.+)\)\z/, 1] || hook.to_s
+    end
+
+    # One line to the user (:hook_notice). During a turn it is a turn
+    # event: the turn's sink (the REPL) and the observers (bridge, log).
+    # Outside one (a plugin's command at the prompt) it is announced with
+    # between_turns: true, which every UI shows as cards are shown.
+    #
+    # +fallback_for+ names what the line stands in for (NOTICE_FALLBACKS):
+    # :display, the answer's display (AnswerDisplay), for a UI that doesn't
+    # render its links; :editor, a ref the viewer could open in its editor
+    # (Web::Capabilities#editor), for a UI or a viewer that can't. A UI that
+    # does leaves the line out; the others, the log among them, show it. An
+    # unknown value is dropped, so the line shows everywhere.
+    # +extra+: more fields for the UIs (a toolkit change's summary).
+    def notify(text, level, hook, fallback_for: nil, extra: {})
+      level = (level || :info).to_sym
+      level = :info unless %i[info warn].include?(level)
+      notice = { type: :hook_notice, hook: hook.to_s, text: text.to_s, level: level,
+                 fallback_for: notice_fallback(fallback_for, hook) }.compact.merge(extra)
+      extension_load = @extension_load.call
+      return extension_load.hold(notice) && nil if extension_load.loading?
+
+      in_turn, sink = @in_turn_sink.call
+      if @anytime_thread.call
+        @announce_anytime.call(notice.merge(between_turns: true))
+      elsif @init_task.call
+        @announce.call(notice.merge(between_turns: true))
+      elsif in_turn
+        @emit.call(sink, notice)
+      else
+        @announce_or_hold.call(notice.merge(between_turns: true))
+      end
+      nil
+    end
+
+    # A guardrails line to the user after load (:guardrail_warning, as the
+    # load failures show): a running turn's event, else announced.
+    def guardrail_notify(message)
+      event = { type: :guardrail_warning, message: message.to_s }
+      in_turn, sink = @in_turn_sink.call
+      in_turn ? @emit.call(sink, event) : @announce_or_hold.call(event)
+      nil
+    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_user(question, options, header, allow_freeform, hook)
+      @question_desk.call.ask_for_hook(question, options, header, allow_freeform, hook)
+    end
+
+    # Cancel the running turn (reason :hook), after a notice that says why.
+    # The gate denies the rest of a tool batch once the controller is
+    # cancelled; the next request ends the turn as :turn_canceled.
+    # @return [Boolean] true when a running turn was cancelled now
+    def stop_turn(reason, hook)
+      ctrl = @cancel_controller.call
+      return false unless ctrl && !ctrl.cancelled?
+
+      notify("stopped the turn: #{reason}", :warn, hook)
+      ctrl.cancel!(:hook, { by: source(hook), reason: reason.to_s })
+    end
+
+    # Cut the streaming generation (reason :hook); the turn goes on and asks
+    # the model again (the loops' cut path). No notice: the plugin posts its
+    # own. The bundle and +reason+ go to the log and the retry's nudge.
+    # @return [Boolean] true when a streaming generation was cut now
+    def stop_generation(reason, hook)
+      ctrl = @cancel_controller.call
+      return false unless ctrl
+
+      ctrl.cancel_generation!(:hook, { by: source(hook), reason: reason.to_s })
+    end
+
+    private
+
+    # A known fallback_for (a String is symbolized), else nil; an unknown
+    # one is logged once at debug.
+    def notice_fallback(value, hook)
+      return if value.nil?
+
+      fallback = value.to_s.to_sym
+      return fallback if NOTICE_FALLBACKS.include?(fallback)
+
+      Log.debug(:hooks, "notice_unknown_fallback", hook: hook.to_s, value: value.to_s) if @unknown_fallbacks.add?(fallback)
+      nil
+    end
+  end
+end

data/lib/samagotchi/hooks/registry.rb

@@ -84,7 +84,7 @@ module Samagotchi
     # What a hook can do beyond reading its event: the Engine's
     # callables, each given the hook's label. +notify+ takes
     # (text:, level:, hook:, and fallback_for: when the hook gave one: what
-    # the line stands in for, Engine#hook_notify) and shows one line to the
+    # the line stands in for, HookRoutes#notify) and shows one line to the
     # user; +ask_user+ takes (question:, options:, header:, allow_freeform:, hook:) and
     # returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
     # cancels the running turn (true when it did); +steer+ takes (text:,
@@ -243,7 +243,7 @@ module Samagotchi
       #   event[:notify].call(text, level: :info, fallback_for: nil)   one line
       #     to the user; fallback_for: :display marks a line that stands in
       #     for the answer's display (event[:present]), which a UI that
-      #     renders the display's links leaves out (Engine#hook_notify)
+      #     renders the display's links leaves out (HookRoutes#notify)
       #   event[:ask_user].call(question:, options:, header: nil, allow_freeform: false)
       #     -> {selected:, freeform:, selected_indices:} or nil (no one to
       #     ask, cancelled, bad options)

data/lib/samagotchi/host_keys.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "log"
+
+module Samagotchi
+  # Where a host's API key named VAR (its api_key_env:) comes from: the
+  # environment variable when set, else, on macOS, the login Keychain's
+  # generic password with service `chi` and account VAR (apps macOS starts,
+  # like the Chi Helper, get a bare environment). SAMAGOTCHI_KEYCHAIN=off
+  # skips the Keychain (specs set it, so nothing they start reads it).
+  #
+  # Keychain hits are cached for the process (every request authorizes,
+  # and a `security` run costs ~0.1 s); misses are not, so a key added to
+  # the Keychain works on the next try. A key is never logged, raised or
+  # shown by inspect.
+  module HostKeys
+    SERVICE = "chi"
+    OFF_ENV = "SAMAGOTCHI_KEYCHAIN"
+
+    # Reads one generic password through /usr/bin/security (by absolute
+    # path: the helper's PATH isn't the shell's) in its own process group,
+    # killed at the deadline: a locked keychain or an access dialog must not
+    # hang a turn. nil on a miss, a non-zero exit, a timeout, no binary, or
+    # off macOS.
+    class Keychain
+      SECURITY = "/usr/bin/security"
+      TIMEOUT = 5
+
+      def initialize(security: SECURITY, timeout: TIMEOUT, host_os: RbConfig::CONFIG["host_os"])
+        @security = security
+        @timeout = timeout
+        @macos = host_os.to_s.include?("darwin")
+      end
+
+      # @return [String, nil]
+      def read(name)
+        return nil unless @macos && File.executable?(@security)
+
+        run(name)
+      end
+
+      def inspect = "#<#{self.class.name} #{@security}>"
+
+      private
+
+      def run(name)
+        reader, writer = IO.pipe
+        pid = Process.spawn(@security, "find-generic-password", "-s", SERVICE, "-a", name, "-w",
+                            in: File::NULL, out: writer, err: File::NULL, pgroup: true)
+        writer.close
+        waiter = Process.detach(pid)
+        unless waiter.join(@timeout)
+          stop(pid, waiter)
+          Log.warn(:config, "keychain_timeout", name: name, seconds: @timeout)
+          return nil
+        end
+        return nil unless waiter.value.success?
+
+        key = reader.read.to_s.chomp
+        key.strip.empty? ? nil : key
+      rescue SystemCallError
+        nil
+      ensure
+        writer&.close unless writer&.closed?
+        reader&.close
+      end
+
+      def stop(pid, waiter)
+        Process.kill(:KILL, -pid)
+      rescue SystemCallError
+        nil
+      ensure
+        waiter.join(1)
+      end
+    end
+
+    # Never reads anything (specs).
+    module NullKeychain
+      def self.read(_name) = nil
+    end
+
+    @keychain = Keychain.new
+    @cache = {}
+    @mutex = Mutex.new
+
+    class << self
+      # @return [#read] where Keychain reads go (specs inject a fake)
+      attr_reader :keychain
+
+      def keychain=(reader)
+        @mutex.synchronize do
+          @keychain = reader
+          @cache.clear
+        end
+      end
+
+      # @return [String, nil] the key: the variable when set, else the Keychain's
+      def fetch(name, env: ENV)
+        from_env(name, env) || from_keychain(name, env: env)
+      end
+
+      # @return [Symbol, nil] :env, :keychain or nil (never the key)
+      def source(name, env: ENV)
+        return :env if from_env(name, env)
+
+        from_keychain(name, env: env) ? :keychain : nil
+      end
+
+      # The Keychain's key for +name+ whatever the environment holds (chi
+      # desktop status asks what the helper will get), nil when off.
+      def from_keychain(name, env: ENV)
+        return nil if off?(env)
+
+        name = name.to_s
+        cached = @mutex.synchronize { @cache[name] }
+        return cached if cached
+
+        key = keychain.read(name)
+        @mutex.synchronize { @cache[name] = key } if key
+        key
+      end
+
+      # SAMAGOTCHI_KEYCHAIN=off (any case).
+      def off?(env = ENV) = env[OFF_ENV].to_s.strip.downcase == "off"
+
+      # Whether this process reads the Keychain: macOS and not switched off
+      # (the messages name the Keychain only then).
+      def available?(host_os = RbConfig::CONFIG["host_os"], env: ENV) = host_os.to_s.include?("darwin") && !off?(env)
+
+      # The command that stores the key for +name+ (prompting for it).
+      def store_command(name) = "security add-generic-password -s #{SERVICE} -a #{name} -w"
+
+      def clear_cache! = @mutex.synchronize { @cache.clear }
+
+      # Names only: the cache holds keys.
+      def inspect = "#<#{name} cached=#{@mutex.synchronize { @cache.keys }.inspect}>"
+
+      private
+
+      def from_env(name, env)
+        value = env[name.to_s].to_s
+        value.strip.empty? ? nil : value
+      end
+    end
+  end
+end

data/lib/samagotchi/kernel_loop.rb

@@ -1067,9 +1067,17 @@ module Samagotchi
     # The error an unknown tool name gets back. A shell-like name with
     # `execute` offered this turn points at `execute`; every other unknown
     # name lists what is offered. Neither echoes the wrong name.
+    #
+    # A tool the session's toolkit leaves out is a real one, so its error
+    # does name it (deliberately, against the rule above): the model learns
+    # it exists and that only the user can load it.
     def unknown_tool_error(name, layers)
       names = @tools.names(layers: layers)
-      if SHELL_LIKE_TOOL_NAMES.include?(name.to_s.downcase) && names.include?("execute")
+      if @tools.respond_to?(:left_out) && @tools.left_out(name, layers: layers)
+        toolkit = @tools.toolkit&.name
+        "Error: #{name} isn't loaded in this session#{" (toolkit #{toolkit})" if toolkit} and can't be loaded from " \
+          "here; only the user can (/toolkit add #{name}). Available: #{names.join(", ")}"
+      elsif SHELL_LIKE_TOOL_NAMES.include?(name.to_s.downcase) && names.include?("execute")
         "Error: no such tool. Shell commands run with `execute` (same arguments)."
       else
         "Error: no such tool. Available: #{names.join(", ")}"

data/lib/samagotchi/llm/adapter_common.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require_relative "../config"
+require_relative "api_key"
+require_relative "errors"
+require_relative "http"
+
+module Samagotchi
+  module LLM
+    # What the chat adapters (OpenAIChat, AnthropicMessages) share: the HTTP
+    # layer and its timeouts, the paged model list, the SSE line loop with
+    # its plain-JSON-error check, and JSON parsing into ProtocolError. The
+    # includer sets @host_name and @http (#build_http); the wire itself (the
+    # body, the headers, the assembly) stays in each adapter.
+    module AdapterCommon
+      MAX_MODEL_PAGES = 20
+      DEFAULT_MODELS_TTL = 60
+      # How much of a 200's non-stream body is read as a possible JSON error.
+      PLAIN_ERROR_LIMIT = 64 * 1024
+
+      private
+
+      # The adapter's LLM::HTTP: the timeouts (#timeouts), one attempt when
+      # +retries+ is false and no +retry_policy+ is given.
+      def build_http(timeout:, open_timeout:, retries:, retry_policy:, sleeper:, first_token_timeout:, api_key:)
+        open_timeout, read_timeout = timeouts(timeout, open_timeout)
+        policy = retry_policy || (retries ? nil : HTTP::RetryPolicy.none)
+        HTTP.new(label: @host_name, open_timeout: open_timeout, read_timeout: read_timeout, retry_policy: policy,
+                 sleeper: sleeper, first_token_timeout: first_token_timeout, api_key: api_key)
+      end
+
+      # [open, read] seconds: server.open_timeout / server.read_timeout,
+      # the open one capped by +open_limit+; a +timeout+ is the read timeout
+      # and caps the open one.
+      def timeouts(timeout, open_limit = nil)
+        open_timeout = Samagotchi::Config.positive_seconds("server.open_timeout")
+        read_timeout = Samagotchi::Config.positive_seconds("server.read_timeout")
+        open_timeout = [open_timeout, open_limit].min if open_limit
+        return [open_timeout, read_timeout] unless timeout
+
+        [[open_timeout, timeout].min, timeout]
+      end
+
+      # Every page of the host's model list (MAX_MODEL_PAGES at most): the
+      # block gives a page's URI for the last page's last_id (nil first).
+      # @return [Array<ModelInfo>]
+      def list_model_pages
+        models = []
+        after = nil
+        MAX_MODEL_PAGES.times do
+          uri = yield(after)
+          body = parse_json(@http.fetch(uri, Net::HTTP::Get.new(uri), log_fields: { purpose: "models" }).body, "model list")
+          models.concat(model_entries(body).map { |raw| model_info(raw) })
+          break unless body.is_a?(Hash) && body["has_more"] && body["last_id"]
+
+          after = body["last_id"].to_s
+        end
+        models
+      end
+
+      # The streamed answer: each `data:` line's parsed payload goes to the
+      # block with the assembly (a fresh +assembly_class+ per attempt: a
+      # retry streams the answer from the start again) and the stream's
+      # shown callback; the assembly's response at the end. +what+ names a
+      # payload in a malformed-JSON error.
+      def stream_assembled(request, cancel_controller, on_retry, log_fields, assembly_class:, what:)
+        assembly = assembly_class.new
+        events = 0
+        other = +""
+        plain = +""
+        restart = lambda do |**event|
+          assembly = assembly_class.new
+          plain = +""
+          on_retry&.call(**event)
+        end
+        @http.stream_lines(URI(request.uri.to_s), request, cancel_controller: cancel_controller, on_retry: restart,
+                                                           log_fields: log_fields) do |line, shown|
+          events += 1 if line.start_with?("data:")
+          other << line[0, 200] if !line.start_with?("data:") && other.length < 200
+          raise_plain_error(plain, line) if events.zero?
+          payload = parse_line(line, what)
+          next unless payload
+
+          yield assembly, payload, shown
+        end
+        # A server that ignores stream: true, or answers with something else
+        # entirely, would otherwise end the turn with no answer and no error.
+        raise ProtocolError.new("#{@host_name}: the response had no stream events: #{other}", host: @host_name) if events.zero?
+
+        assembly.response
+      end
+
+      # A 200 whose body is a plain JSON error instead of a stream (OpenRouter
+      # sends an upstream 503 so): raised, from inside the stream so it is
+      # retried by its kind, once the lines so far parse as an error object.
+      def raise_plain_error(plain, line)
+        return if line.empty? || line.start_with?(":") || (plain.empty? && !line.start_with?("{"))
+        return if plain.bytesize > PLAIN_ERROR_LIMIT
+
+        plain << line << "\n"
+        error = ProviderErrors.from_error_body(plain, host: @host_name)
+        raise error if error
+      end
+
+      # The parsed payload of a `data:` line; nil for `event:` lines, blank
+      # lines, comments and [DONE]. An error event raises its ProviderError.
+      def parse_line(line, what)
+        error = HTTP.sse_error(line, host: @host_name)
+        raise error if error
+        return nil unless line.start_with?("data:")
+
+        data = line.delete_prefix("data:").strip
+        return nil if data.empty? || data == "[DONE]"
+
+        payload = parse_json(data, what)
+        payload.is_a?(Hash) ? payload : nil
+      end
+
+      def parse_json(text, what)
+        JSON.parse(text.to_s)
+      rescue JSON::ParserError => e
+        raise ProtocolError.new("#{@host_name}: malformed #{what}: #{e.message[0, 200]}", host: @host_name)
+      end
+
+      # A JSON POST to +url+: Content-Type, then +headers+ in order, the
+      # body generated from +body+.
+      def json_post(url, body, headers = {})
+        Net::HTTP::Post.new(URI(url)).tap do |request|
+          request["Content-Type"] = "application/json"
+          headers.each { |name, value| request[name] = value }
+          request.body = JSON.generate(body)
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/llm/anthropic_assembly.rb

@@ -102,9 +102,11 @@ module Samagotchi
       end
 
       # The usage so far as an OpenAI-shaped `usage` object, nil when the
-      # server sent no counts.
+      # server sent no counts, or only zeros (Fireworks' message_start: its
+      # counts come in the last message_delta; a 0 read as an empty context
+      # in the web's ctx meter while the answer streamed).
       def usage_payload
-        return nil if @usage.empty?
+        return nil if @usage.values.none?(&:positive?)
 
         read = @usage["cache_read_input_tokens"].to_i
         write = @usage["cache_creation_input_tokens"].to_i