lex-llm 0.7.6 → 0.8.4

data/lib/legion/extensions/llm/canonical/tool_call.rb

@@ -2,39 +2,40 @@
 
 require 'securerandom'
 
-# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
+      # -- required for Data.define block scope
       module Canonical
-        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
         # Canonical tool call with source enum and compliance fields.
         # Ports field vocabulary from Legion::LLM::Types::ToolCall.
         # Source enum per R7: :client | :registry | :special | :extension | :mcp
         # Compliance fields per R8: data_handling_classification, policy_decision
+        # arguments is a Hash only (O03a): JSON-string arguments are a provider
+        # wire spelling parsed at the provider translator edge (10 U2).
         ToolCall = ::Data.define(
           :id, :exchange_id, :name, :arguments, :source,
           :status, :duration_ms, :result, :error,
           :started_at, :finished_at, :category,
-          :data_handling_classification, :policy_decision
+          :data_handling_classification, :policy_decision, :metadata
         ) do
-          SOURCE_VALUES = %i[client registry special extension mcp].freeze
-          STATUS_VALUES = %i[pending running success error].freeze
-
           # Build from keyword args (primary constructor).
+          # arguments: nil means "no arguments" and normalizes to {} (documented
+          # default, not tolerance).
           def self.build(
             name:, id: nil, exchange_id: nil, arguments: nil, source: nil,
             status: nil, duration_ms: nil, result: nil, error: nil,
             started_at: nil, finished_at: nil, category: nil,
-            data_handling_classification: nil, policy_decision: nil
+            data_handling_classification: nil, policy_decision: nil, metadata: {}
           )
             new(
               id: id || "call_#{SecureRandom.hex(12)}",
               exchange_id: exchange_id,
-              name: name,
-              arguments: arguments || {},
-              source: source,
-              status: status,
+              name: Strict.expect_type!(name, [::String], self::BUILD_SITE, :name),
+              arguments: arguments.nil? ? {} : Strict.expect_type!(arguments, [::Hash], self::BUILD_SITE, :arguments),
+              source: normalize_enum!(source, self::SOURCE_VALUES, self::BUILD_SITE, :source),
+              status: normalize_enum!(status, self::STATUS_VALUES, self::BUILD_SITE, :status),
               duration_ms: duration_ms,
               result: result,
               error: error,
@@ -42,38 +43,30 @@ module Legion
               finished_at: finished_at,
               category: category,
               data_handling_classification: data_handling_classification,
-              policy_decision: policy_decision
+              policy_decision: policy_decision,
+              metadata: Strict.metadata!(metadata, self::BUILD_SITE)
             )
           end
 
           # Build from a Hash (raw provider response or deserialized wire payload).
-          def self.from_hash(hash)
-            return nil if hash.nil?
-
-            h = hash.transform_keys(&:to_sym)
-
-            # Normalize source to symbol
-            source_raw = h[:source]
-            h[:source] = source_raw&.to_sym if source_raw.is_a?(String)
-
-            # Normalize status to symbol
-            status_raw = h[:status]
-            h[:status] = status_raw&.to_sym if status_raw.is_a?(String)
+          def self.from_hash(source)
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(**hash, metadata:)
+          end
 
-            # Parse arguments if they're a JSON string
-            args = h[:arguments]
-            if args.is_a?(String) && !args.empty?
-              begin
-                h[:arguments] = Legion::JSON.load(args)
-              rescue Legion::JSON::ParseError => e
-                Legion::Logging.debug("[lex-llm][canonical][tool_call] arguments not parseable as JSON, leaving as string: #{e.message}")
-              end
-            end
+          # L6: declared enums validated at construction, in both factories.
+          def self.normalize_enum!(value, allowed, site, member)
+            return nil if value.nil?
 
-            build(**h)
+            value_sym = value.is_a?(::String) ? value.to_sym : value
+            Strict.enum!(value_sym, allowed, site, member)
           end
 
-          # Return a new ToolCall with execution result attached.
+          # Return a new ToolCall with execution result attached. The strict
+          # constructor re-validates every carried member (status enum
+          # included) — the escape-hatch .new of the pre-H1 world is gone.
           def with_result(result:, status:, duration_ms: nil, finished_at: nil)
             self.class.new(
               id: id,
@@ -89,7 +82,8 @@ module Legion
               finished_at: finished_at || ::Time.now,
               category: category,
               data_handling_classification: data_handling_classification,
-              policy_decision: policy_decision
+              policy_decision: policy_decision,
+              metadata: metadata
             )
           end
 
@@ -116,29 +110,25 @@ module Legion
             to_h.to_json(*)
           end
 
-          # Subset for audit/ledger emission.
-          def to_audit_hash
-            {
-              id: id,
-              name: name,
-              arguments: arguments,
-              status: status,
-              duration_ms: duration_ms,
-              error: error,
-              exchange_id: exchange_id,
-              source: source,
-              category: category,
-              data_handling_classification: data_handling_classification,
-              policy_decision: policy_decision
-            }.compact
+          # H1: the single strict constructor — .new runs the same member
+          # contract as the factories; the factories fill their defaults and
+          # delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:name] = Strict.expect_type!(values[:name], [::String], site, :name)
+            values[:arguments] = values[:arguments].nil? ? {} : Strict.expect_type!(values[:arguments], [::Hash], site, :arguments)
+            values[:source] = normalize_enum!(values[:source], self::SOURCE_VALUES, site, :source)
+            values[:status] = normalize_enum!(values[:status], self::STATUS_VALUES, site, :status)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
           end
         end
 
         ToolCall::SOURCE_VALUES = %i[client registry special extension mcp].freeze
         ToolCall::STATUS_VALUES = %i[pending running success error].freeze
-        # rubocop:enable Lint/ConstantDefinitionInBlock
+        ToolCall::BUILD_SITE = 'Canonical::ToolCall.build'
+        ToolCall::FROM_HASH_SITE = 'Canonical::ToolCall.from_hash'
+        ToolCall::NEW_SITE = 'Canonical::ToolCall.new'
       end
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/legion/extensions/llm/canonical/tool_definition.rb

@@ -4,21 +4,20 @@ module Legion
   module Extensions
     module Llm
       module Canonical
-        TOOL_NAME_MAX_LENGTH = 64
         OBJECT_SCHEMA_KEYWORDS    = %i[properties required additionalProperties].freeze
         COMPOSITE_SCHEMA_KEYWORDS = %i[oneOf anyOf allOf enum $ref $defs definitions].freeze
 
         # Canonical tool definition.
-        # Ports field vocabulary from Legion::LLM::Types::ToolDefinition.
-        ToolDefinition = ::Data.define(:name, :description, :parameters, :source) do
+        # Ports field vocabulary from Legion::LLM::Types::ToolDefinition. # -- required for Data.define block scope
+        ToolDefinition = ::Data.define(:name, :description, :parameters, :source, :metadata) do
           def self.normalize_parameters(parameters)
             empty = { type: 'object', properties: {} }
             return empty if parameters.nil?
 
-            schema = if parameters.respond_to?(:transform_keys)
-                       parameters.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
-                     end
-            return empty if schema.nil? || schema.empty?
+            Strict.expect_type!(parameters, [::Hash], self::NORMALIZE_PARAMETERS_SITE, :parameters) unless parameters.is_a?(::Hash)
+
+            schema = parameters.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+            return empty if schema.empty?
             return schema if schema.key?(:type)
             return schema.merge(type: 'object') if OBJECT_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }
             return schema if COMPOSITE_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }
@@ -26,53 +25,50 @@ module Legion
             { type: 'object', properties: schema }
           end
 
-          # Build from keyword args (primary constructor).
-          def self.build(name:, description: '', parameters: nil, source: nil)
+          # Build from keyword args (primary constructor). M5: the name is the
+          # authoritative client/registry fact — never rewritten, stripped,
+          # truncated, or fabricated here; per-dialect name constraints belong
+          # to the provider translator edge. source is explicit or absent —
+          # never fabricated ({ type: :builtin } is deleted).
+          def self.build(name:, description: '', parameters: nil, source: nil, metadata: {})
             new(
-              sanitize_tool_name(name),
-              description.to_s,
+              name,
+              description,
               normalize_parameters(parameters),
-              source || { type: :builtin }
+              source,
+              Strict.metadata!(metadata, self::BUILD_SITE)
             )
           end
 
           # Build from a Hash (raw provider response or deserialized wire payload).
-          def self.from_hash(hash, source: nil)
-            return nil if hash.nil?
-
-            normalized = hash.respond_to?(:transform_keys) ? hash.transform_keys(&:to_sym) : {}
+          # Canonical keys only (O03a): edges pass `parameters`, not `input_schema`.
+          def self.from_hash(source)
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
             build(
-              name: normalized[:name],
-              description: normalized[:description],
-              parameters: normalized[:parameters] || normalized[:input_schema],
-              source: source || normalized[:source]
+              name: hash[:name],
+              description: hash[:description],
+              parameters: hash[:parameters],
+              source: hash[:source],
+              metadata:
             )
           end
 
-          # Build from a registry entry (extension/registry tool metadata).
-          def self.from_registry_entry(entry)
-            source = {
-              type: entry[:tool_class] ? :registry : :extension,
-              tool_class: entry[:tool_class],
-              extension: entry[:extension],
-              runner: entry[:runner],
-              function: entry[:function]
-            }.compact
+          # M5: a tool name is authoritative — missing or empty is a contract
+          # error, never a fabricated label.
+          def self.require_name!(name, site)
+            raise ArgumentError, "#{site}: name must be a non-empty String, got #{name.class}: #{name.inspect}" unless name.is_a?(::String) && !name.empty?
 
-            build(
-              name: entry[:name],
-              description: entry[:description],
-              parameters: entry[:input_schema] || entry[:parameters],
-              source: source.compact
-            )
+            name
           end
 
-          # Sanitize a tool name to be safe for all wire formats.
-          def self.sanitize_tool_name(raw)
-            name = raw.to_s.tr('.', '_')
-            name = name.gsub(/[^a-zA-Z0-9_-]/, '')
-            name = name[0, TOOL_NAME_MAX_LENGTH] if name.length > TOOL_NAME_MAX_LENGTH
-            name.empty? ? 'tool' : name
+          # M5: description is a String; absence is the empty string (the
+          # documented no-description value), wrong class raises.
+          def self.description_value!(description, site)
+            return '' if description.nil?
+
+            Strict.expect_type!(description, [::String], site, :description)
           end
 
           def params_schema
@@ -85,11 +81,7 @@ module Legion
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
           def to_h
-            {
-              name: name,
-              description: description,
-              parameters: parameters
-            }.compact.reject { |k, v| k == :description && v == '' }
+            super.compact
           end
 
           # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
@@ -100,7 +92,25 @@ module Legion
           def to_json(*)
             to_h.to_json(*)
           end
+
+          # H1/M5: the single strict constructor — .new runs the same member
+          # contract as the factories (authoritative name, String
+          # description, normalized parameters, explicit-or-absent source);
+          # the factories fill their defaults and delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:name] = require_name!(values[:name], site)
+            values[:description] = description_value!(values[:description], site)
+            values[:parameters] = normalize_parameters(values[:parameters])
+            values[:source] = Strict.expect_type!(values[:source], [::Hash], site, :source)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
+
+        ToolDefinition::BUILD_SITE = 'Canonical::ToolDefinition.build'
+        ToolDefinition::FROM_HASH_SITE = 'Canonical::ToolDefinition.from_hash'
+        ToolDefinition::NEW_SITE = 'Canonical::ToolDefinition.new'
+        ToolDefinition::NORMALIZE_PARAMETERS_SITE = 'Canonical::ToolDefinition.normalize_parameters'
       end
     end
   end

data/lib/legion/extensions/llm/canonical/tool_schema.rb

@@ -4,40 +4,33 @@ module Legion
   module Extensions
     module Llm
       module Canonical
-        # Extracts and normalizes tool schemas from heterogeneous sources.
+        # Extracts and normalizes tool schemas from ToolDefinition ONLY (04 §6).
+        # A schema extractor that tolerates raw hashes is a hidden path over the
+        # canonical type — wrong-class input raises (L3).
         module ToolSchema
           EMPTY_OBJECT = { type: 'object', properties: {} }.freeze
 
           module_function
 
-          def extract(tool)
-            raw = raw_schema(tool)
-            ToolDefinition.normalize_parameters(raw)
+          def extract(tool_definition)
+            require_tool_definition!(tool_definition, 'ToolSchema.extract')
+            ToolDefinition.normalize_parameters(tool_definition.parameters)
           end
 
-          def raw_schema(tool)
-            return nil if tool.nil?
-            return tool.params_schema if tool.respond_to?(:params_schema) && tool.params_schema
-            return tool.parameters if tool.respond_to?(:parameters) && tool.parameters
-
-            return unless tool.respond_to?(:[])
-
-            tool[:parameters] || tool['parameters'] || tool[:input_schema] || tool['input_schema'] ||
-              tool[:params_schema] || tool['params_schema']
+          def tool_name(tool_definition)
+            require_tool_definition!(tool_definition, 'ToolSchema.tool_name')
+            tool_definition.name
           end
 
-          def tool_name(tool)
-            return tool.name if tool.respond_to?(:name) && !tool.is_a?(Hash)
-            return tool[:name] || tool['name'] if tool.respond_to?(:[])
-
-            'unknown'
+          def tool_description(tool_definition)
+            require_tool_definition!(tool_definition, 'ToolSchema.tool_description')
+            tool_definition.description
           end
 
-          def tool_description(tool)
-            return tool.description if tool.respond_to?(:description) && !tool.is_a?(Hash)
-            return (tool[:description] || tool['description'] || '').to_s if tool.respond_to?(:[])
+          def require_tool_definition!(tool_definition, site)
+            return tool_definition if tool_definition.is_a?(ToolDefinition)
 
-            ''
+            raise ArgumentError, "#{site}: expected Canonical::ToolDefinition, got #{tool_definition.class}"
           end
         end
       end

data/lib/legion/extensions/llm/canonical/usage.rb

@@ -4,56 +4,44 @@
 module Legion
   module Extensions
     module Llm
+      # -- required for Data.define block scope
       module Canonical
-        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
         # Canonical usage/metering data for a response.
         # Ports field vocabulary from lex-llm Tokens and legion-llm Types.
         # Includes non-token units extension point per G20b.
+        # Canonical keys only (O03a): provider spellings are translated at the edges.
         Usage = ::Data.define(
           :input_tokens, :output_tokens, :cache_read_tokens, :cache_write_tokens,
-          :thinking_tokens, :units
+          :thinking_tokens, :units, :metadata
         ) do
-          USAGE_KNOWN_KEYS = %i[input_tokens output_tokens cache_read_tokens cache_write_tokens
-                                thinking_tokens units].freeze
-
-          # Build from a Hash (raw provider response or deserialized wire payload).
-          # Accepts both canonical key names and legacy provider spellings.
-          def self.from_hash(source)
-            return nil if source.nil? || source.empty?
-
-            h = source.transform_keys(&:to_sym)
-
-            # Normalize legacy key names
-            h[:input_tokens] ||= h.delete(:input) || h.delete(:prompt_tokens)
-            h[:output_tokens] ||= h.delete(:output) || h.delete(:completion_tokens)
-            h[:cache_read_tokens] ||= h.delete(:cached) || h.delete(:cache_read)
-            h[:cache_write_tokens] ||= h.delete(:cache_creation) || h.delete(:cache_write)
-            h[:thinking_tokens] ||= h.delete(:thinking) || h.delete(:reasoning)
-
-            # Extract nested details (OpenAI prompt_tokens_details / input_tokens_details)
-            h[:cache_read_tokens] ||= dig_nested(h, :prompt_tokens_details, :cached_tokens) ||
-                                      dig_nested(h, :input_tokens_details, :cached_tokens)
-            h[:thinking_tokens] ||= dig_nested(h, :completion_tokens_details, :reasoning_tokens) ||
-                                    dig_nested(h, :output_tokens_details, :reasoning_tokens)
-
-            # Extract units (non-token extension point — G20b)
-            units = h.delete(:units) || {}
-
+          # rubocop:disable Metrics/ParameterLists -- factory methods have many params
+          # Build from keyword args (primary constructor).
+          def self.build(
+            input_tokens: nil, output_tokens: nil, cache_read_tokens: nil,
+            cache_write_tokens: nil, thinking_tokens: nil, units: nil, metadata: {}
+          )
             new(
-              input_tokens: h[:input_tokens],
-              output_tokens: h[:output_tokens],
-              cache_read_tokens: h[:cache_read_tokens],
-              cache_write_tokens: h[:cache_write_tokens],
-              thinking_tokens: h[:thinking_tokens],
-              units: units
+              input_tokens:, output_tokens:, cache_read_tokens:, cache_write_tokens:,
+              thinking_tokens:, units: units || {}, metadata: Strict.metadata!(metadata, self::BUILD_SITE)
             )
           end
+          # rubocop:enable Metrics/ParameterLists
 
-          def self.dig_nested(hash, details_key, value_key)
-            details = hash[details_key]
-            return nil unless details.is_a?(Hash)
-
-            details[value_key] || details[value_key.to_s]
+          # Build from a Hash (raw provider response or deserialized wire payload).
+          # from_hash({}) is a valid all-nil Usage (the no-usage object), never nil.
+          def self.from_hash(source)
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(
+              input_tokens: hash[:input_tokens],
+              output_tokens: hash[:output_tokens],
+              cache_read_tokens: hash[:cache_read_tokens],
+              cache_write_tokens: hash[:cache_write_tokens],
+              thinking_tokens: hash[:thinking_tokens],
+              units: hash[:units] || {},
+              metadata:
+            )
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
@@ -75,8 +63,27 @@ module Legion
             [input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
              thinking_tokens].compact.sum
           end
+
+          # H1/M3: the single strict constructor. .new validates the token
+          # members as Integers (a string count would raise deep in
+          # StreamAccumulator#total_tokens instead of at construction) and
+          # units as a Hash. The factories fill their defaults and delegate
+          # here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:input_tokens] = Strict.expect_type!(values[:input_tokens], [::Integer], site, :input_tokens)
+            values[:output_tokens] = Strict.expect_type!(values[:output_tokens], [::Integer], site, :output_tokens)
+            values[:cache_read_tokens] = Strict.expect_type!(values[:cache_read_tokens], [::Integer], site, :cache_read_tokens)
+            values[:cache_write_tokens] = Strict.expect_type!(values[:cache_write_tokens], [::Integer], site, :cache_write_tokens)
+            values[:thinking_tokens] = Strict.expect_type!(values[:thinking_tokens], [::Integer], site, :thinking_tokens)
+            values[:units] = values[:units].nil? ? {} : Strict.expect_type!(values[:units], [::Hash], site, :units)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
-        # rubocop:enable Lint/ConstantDefinitionInBlock
+
+        Usage::BUILD_SITE = 'Canonical::Usage.build'
+        Usage::FROM_HASH_SITE = 'Canonical::Usage.from_hash'
+        Usage::NEW_SITE = 'Canonical::Usage.new'
       end
     end
   end

data/lib/legion/extensions/llm/canonical.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require_relative 'canonical/strict'
 require_relative 'canonical/thinking'
+require_relative 'canonical/thinking_config'
 require_relative 'canonical/usage'
 require_relative 'canonical/params'
 require_relative 'canonical/content_block'
@@ -26,17 +28,17 @@ module Legion
       module Canonical
         CONTRACT_VERSION = '1.0.0'
 
-        # Available canonical types.
+        # Available canonical types (the frozen 04 §1 inventory).
         TYPES = %i[
-          Thinking Usage Params ContentBlock
-          ToolDefinition ToolCall Message
-          Request Response Chunk
+          Message ContentBlock ToolCall ToolDefinition ToolSchema
+          Params Thinking Thinking::Config
+          Request Response Chunk Usage
         ].freeze
 
         class << self
           # List all canonical type classes.
           def types
-            TYPES.map { |name| const_get(name) }
+            TYPES.map { |name| name.to_s.split('::').reduce(self) { |mod, part| mod.const_get(part) } }
           end
 
           # Check if a given constant name is a registered canonical type.

data/lib/legion/extensions/llm/configuration.rb

@@ -26,23 +26,49 @@ module Legion
             Array(keys).each { |key| option(key.to_sym) }
           end
 
+          include Legion::Logging::Helper
+
+          # L5: the log defaults, read from the settings system (the ENV
+          # reads are deleted). A configured log_level Symbol/String names a
+          # Logger constant — an unknown name is a configuration error (it
+          # raises, it does not fall back).
+          def log_settings_defaults
+            {
+              level: log_level_value(llm_setting(:log_level)),
+              stream_debug: llm_setting(:log_stream_debug) == true
+            }
+          end
+
           private
 
           def option_keys = @option_keys ||= []
           def defaults = @defaults ||= {}
-          private :option
+
+          def log_level_value(value)
+            return Logger::INFO if value.nil?
+
+            value.is_a?(::Integer) ? value : Logger.const_get(value.to_s.upcase)
+          end
+
+          def llm_setting(key)
+            return nil unless defined?(::Legion::Settings) && ::Legion::Settings.respond_to?(:dig)
+
+            ::Legion::Settings.dig(:extensions, :llm, key)
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'llm.configuration.setting', key:)
+            nil
+          end
+          private :option, :log_level_value, :llm_setting
         end
 
         # System-level options are declared here.
         # Provider-specific options are declared in each provider extension via
         # `self.configuration_options`.
-        option :default_model, nil
-        option :default_embedding_model, nil
-        option :default_moderation_model, nil
-        option :default_image_model, nil
-        option :default_transcription_model, nil
-
-        option :model_registry_file, -> { File.expand_path('models.json', __dir__) }
+        # H4: the dormant default_model / default_*_model options are deleted —
+        # a model-defaulting authority with no consumer (verified in-repo and
+        # in consumer gems). Model selection belongs to the router.
+        # The model_registry_file option is deleted with the Models catalog
+        # (the second inventory) — the SSOT registry is the only inventory.
 
         option :request_timeout, 300
         option :max_retries, 3
@@ -53,8 +79,12 @@ module Legion
 
         option :logger, nil
         option :log_file, -> { $stdout }
-        option :log_level, -> { ENV['LEGION_LLM_DEBUG'] ? Logger::DEBUG : Logger::INFO }
-        option :log_stream_debug, -> { ENV['LEGION_LLM_STREAM_DEBUG'] == 'true' }
+        # L5: the ENV reads (LEGION_LLM_DEBUG / LEGION_LLM_STREAM_DEBUG) are
+        # deleted — every tunable lives in the settings system:
+        # extensions.llm.log_level (Symbol/Integer; Logger::INFO when unset)
+        # and extensions.llm.log_stream_debug (boolean; false when unset).
+        option :log_level, -> { self.class.log_settings_defaults[:level] }
+        option :log_stream_debug, -> { self.class.log_settings_defaults[:stream_debug] }
         option :log_regexp_timeout, -> { Regexp.respond_to?(:timeout) ? (Regexp.timeout || 1.0) : nil }
 
         # Prompt caching