spurline-docs 0.3.0

data/lib/spurline/tools/base.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+require "set"
+
+module Spurline
+  module Tools
+    # Base class for all Spurline tools. Tools are atomic — they cannot invoke
+    # other tools (ADR-003). Composition belongs in the Skill layer.
+    #
+    # Subclasses must implement #call with keyword arguments matching
+    # the tool's parameter schema.
+    class Base
+      class << self
+        def tool_name(name = nil)
+          if name
+            @tool_name = name.to_sym
+          else
+            @tool_name || self.name&.split("::")&.last&.gsub(/([a-z])([A-Z])/, '\1_\2')&.downcase&.to_sym
+          end
+        end
+
+        def description(desc = nil)
+          if desc
+            @description = desc
+          else
+            @description || ""
+          end
+        end
+
+        def parameters(params = nil)
+          if params
+            @parameters = params
+          else
+            @parameters || {}
+          end
+        end
+
+        # Declares a secret this tool needs injected at execution time.
+        # Secrets are resolved by the framework and are not part of the tool schema.
+        def secret(name, description: nil)
+          @declared_secrets ||= []
+          @declared_secrets << { name: name.to_sym, description: description }
+        end
+
+        # Returns all declared secrets for this class, including inherited ones.
+        def declared_secrets
+          own = @declared_secrets || []
+          if superclass.respond_to?(:declared_secrets)
+            superclass.declared_secrets + own
+          else
+            own
+          end
+        end
+
+        # Returns sensitive argument names from schema metadata and declared secrets.
+        #
+        # A parameter is treated as sensitive when its schema property includes:
+        #   sensitive: true
+        def sensitive_parameters
+          schema = parameters || {}
+          properties = schema[:properties] || schema["properties"] || {}
+          schema_sensitive = Set.new
+          if properties.is_a?(Hash)
+            properties.each do |name, definition|
+              next unless definition.is_a?(Hash)
+
+              sensitive = definition[:sensitive]
+              sensitive = definition["sensitive"] if sensitive.nil?
+              schema_sensitive << name.to_sym if sensitive
+            end
+          end
+
+          secret_names = (declared_secrets || []).map { |secret| secret[:name] }
+          schema_sensitive | Set.new(secret_names)
+        end
+
+        # Declares that this tool requires confirmation before execution.
+        def requires_confirmation(val = true)
+          @requires_confirmation = val
+        end
+
+        def requires_confirmation?
+          return @requires_confirmation unless @requires_confirmation.nil?
+
+          return superclass.requires_confirmation? if superclass.respond_to?(:requires_confirmation?)
+
+          false
+        end
+
+        # Declares a timeout in seconds for tool execution.
+        def timeout(seconds = nil)
+          unless seconds.nil?
+            @timeout = seconds
+          else
+            @timeout
+          end
+        end
+
+        # Declares that tool calls are idempotent and can be cached by key.
+        def idempotent(val = true)
+          @idempotent = val
+        end
+
+        def idempotent?
+          return @idempotent unless @idempotent.nil?
+
+          return superclass.idempotent? if superclass.respond_to?(:idempotent?)
+
+          false
+        end
+
+        # Declares which params form the idempotency key.
+        def idempotency_key(*params)
+          @idempotency_key_params = params.flatten.map(&:to_sym)
+        end
+
+        def idempotency_key_params
+          return @idempotency_key_params if instance_variable_defined?(:@idempotency_key_params)
+
+          return superclass.idempotency_key_params if superclass.respond_to?(:idempotency_key_params)
+
+          nil
+        end
+
+        # Declares cache TTL (seconds) for idempotent results.
+        def idempotency_ttl(seconds = nil)
+          unless seconds.nil?
+            @idempotency_ttl = seconds
+          end
+          @idempotency_ttl
+        end
+
+        def idempotency_ttl_value
+          ttl = idempotency_ttl
+          return ttl unless ttl.nil?
+
+          if superclass.respond_to?(:idempotency_ttl_value)
+            return superclass.idempotency_ttl_value
+          end
+
+          default_ttl = Spurline.config.idempotency_default_ttl
+          return default_ttl unless default_ttl.nil?
+
+          Spurline::Tools::Idempotency::Ledger::DEFAULT_TTL
+        end
+
+        # Declares a custom key lambda taking the final args hash.
+        def idempotency_key_fn(fn = nil)
+          @idempotency_key_fn = fn if fn
+          @idempotency_key_fn
+        end
+
+        # Declares that tool expects injected _scope keyword argument.
+        def scoped(val = true)
+          @scoped = val
+        end
+
+        def scoped?
+          return @scoped unless @scoped.nil?
+
+          return superclass.scoped? if superclass.respond_to?(:scoped?)
+
+          false
+        end
+
+        # Validates arguments against the tool's parameter schema.
+        # Checks required properties and type mismatches.
+        # Returns true if valid, raises ConfigurationError if invalid.
+        def validate_arguments!(args)
+          schema = parameters
+          return true if schema.empty?
+
+          properties = schema[:properties] || schema["properties"] || {}
+          required = schema[:required] || schema["required"] || []
+
+          # Check required properties
+          required.each do |prop|
+            prop_sym = prop.to_sym
+            unless args.key?(prop_sym) || args.key?(prop.to_s)
+              raise Spurline::ConfigurationError,
+                "Tool '#{tool_name}' missing required parameter '#{prop}'. " \
+                "Required parameters: #{required.join(", ")}."
+            end
+          end
+
+          true
+        end
+      end
+
+      def name
+        self.class.tool_name
+      end
+
+      def call(**_args)
+        raise NotImplementedError,
+          "#{self.class.name} must implement #call. Tools are leaf nodes (ADR-003) — " \
+          "they receive arguments and return a result. Use a Spurline::Skill for composition."
+      end
+
+      # Returns the tool schema for the LLM adapter.
+      def to_schema
+        {
+          name: name,
+          description: self.class.description,
+          input_schema: self.class.parameters,
+        }
+      end
+    end
+  end
+end

data/lib/spurline/tools/idempotency.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Spurline
+  module Tools
+    module Idempotency
+      # Computes idempotency keys from tool name and arguments.
+      class KeyComputer
+        # Computes a deterministic key for a tool call.
+        #
+        # @param tool_name [Symbol] Tool identifier
+        # @param args [Hash] Tool call arguments
+        # @param key_params [Array<Symbol>, nil] Specific params to include (nil = all)
+        # @param key_fn [Proc, nil] Custom key computation lambda
+        # @return [String] Deterministic key string "tool_name:hash"
+        #
+        # Key computation:
+        #   1. If key_fn provided: "#{tool_name}:#{key_fn.call(args)}"
+        #   2. If key_params provided: SHA256 of only those params
+        #   3. Default: SHA256 of all args (canonical JSON with sorted keys)
+        def self.compute(tool_name:, args:, key_params: nil, key_fn: nil)
+          prefix = tool_name.to_s
+
+          hash = if key_fn
+            key_fn.call(args).to_s
+          elsif key_params
+            canonical_hash(args.slice(*key_params))
+          else
+            canonical_hash(args)
+          end
+
+          "#{prefix}:#{hash}"
+        end
+
+        # Produces a deterministic hash of arguments.
+        # Sorts keys recursively for canonical representation.
+        def self.canonical_hash(args)
+          json = JSON.generate(canonicalize(args))
+          Digest::SHA256.hexdigest(json)
+        end
+
+        # Recursively sorts hash keys for deterministic serialization.
+        def self.canonicalize(obj)
+          case obj
+          when Hash
+            obj.sort_by { |k, _| k.to_s }.map { |k, v| [k.to_s, canonicalize(v)] }.to_h
+          when Array
+            obj.map { |v| canonicalize(v) }
+          else
+            obj
+          end
+        end
+      end
+
+      # Session-scoped cache for idempotent tool results.
+      # Wraps a plain hash (from session.metadata[:idempotency_ledger]).
+      class Ledger
+        DEFAULT_TTL = 86_400 # 24 hours
+
+        # @param store [Hash] The backing hash (from session.metadata)
+        def initialize(store)
+          @store = store
+          @store[:entries] ||= {}
+        end
+
+        # Returns true if key exists and is not expired.
+        #
+        # @param key [String] Idempotency key
+        # @param ttl [Integer] TTL in seconds
+        # @return [Boolean]
+        def cached?(key, ttl: DEFAULT_TTL)
+          entry = @store[:entries][key]
+          return false unless entry
+
+          age = Time.now.to_f - entry[:timestamp]
+          if age > ttl
+            @store[:entries].delete(key) # Lazy cleanup
+            false
+          else
+            true
+          end
+        end
+
+        # Returns the cached result, or nil if not cached/expired.
+        #
+        # @param key [String] Idempotency key
+        # @param ttl [Integer] TTL in seconds
+        # @return [String, nil]
+        def fetch(key, ttl: DEFAULT_TTL)
+          return nil unless cached?(key, ttl: ttl)
+
+          @store[:entries][key][:result]
+        end
+
+        # Stores a result with timestamp.
+        #
+        # @param key [String] Idempotency key
+        # @param result [String] Serialized tool result
+        # @param args_hash [String] Hash of the arguments (for conflict detection)
+        # @param ttl [Integer] TTL in seconds (stored for reference)
+        def store!(key, result:, args_hash:, ttl: DEFAULT_TTL)
+          @store[:entries][key] = {
+            result: result,
+            args_hash: args_hash,
+            timestamp: Time.now.to_f,
+            ttl: ttl,
+          }
+        end
+
+        # Returns true if key exists with different arguments.
+        # Same key + different args = bug in calling code.
+        #
+        # @param key [String] Idempotency key
+        # @param args_hash [String] Hash of current arguments
+        # @return [Boolean]
+        def conflict?(key, args_hash)
+          entry = @store[:entries][key]
+          return false unless entry
+
+          entry[:args_hash] != args_hash
+        end
+
+        # Returns age of cached entry in milliseconds, or nil.
+        def cache_age_ms(key)
+          entry = @store[:entries][key]
+          return nil unless entry
+
+          ((Time.now.to_f - entry[:timestamp]) * 1000).round
+        end
+
+        # Removes all expired entries.
+        def cleanup_expired!(default_ttl: DEFAULT_TTL)
+          now = Time.now.to_f
+          @store[:entries].delete_if do |_key, entry|
+            ttl = entry[:ttl] || default_ttl
+            (now - entry[:timestamp]) > ttl
+          end
+        end
+
+        # Empties the entire ledger.
+        def clear!
+          @store[:entries] = {}
+        end
+
+        # Returns the number of entries.
+        def size
+          @store[:entries].size
+        end
+
+        # Returns true if the ledger has no entries.
+        def empty?
+          @store[:entries].empty?
+        end
+      end
+
+      # Per-tool idempotency configuration.
+      # Built from class-level declarations or DSL config.
+      class Config
+        attr_reader :enabled, :key_params, :ttl, :key_fn
+
+        # @param enabled [Boolean] Whether idempotency is enabled for this tool
+        # @param key_params [Array<Symbol>, nil] Which params form the key (nil = all)
+        # @param ttl [Integer] TTL in seconds
+        # @param key_fn [Proc, nil] Custom key computation lambda
+        def initialize(enabled: false, key_params: nil, ttl: Ledger::DEFAULT_TTL, key_fn: nil)
+          @enabled = enabled
+          @key_params = key_params
+          @ttl = ttl
+          @key_fn = key_fn
+          freeze
+        end
+
+        def enabled?
+          @enabled
+        end
+
+        # Builds a Config from a tool class's class-level declarations.
+        #
+        # @param tool_class [Class] Tool class with idempotency declarations
+        # @return [Config]
+        def self.from_tool_class(tool_class)
+          new(
+            enabled: tool_class.respond_to?(:idempotent?) && tool_class.idempotent?,
+            key_params: tool_class.respond_to?(:idempotency_key_params) ? tool_class.idempotency_key_params : nil,
+            ttl: tool_class.respond_to?(:idempotency_ttl_value) ? tool_class.idempotency_ttl_value : Ledger::DEFAULT_TTL,
+            key_fn: tool_class.respond_to?(:idempotency_key_fn) ? tool_class.idempotency_key_fn : nil,
+          )
+        end
+
+        # Builds a Config from DSL options hash.
+        # DSL wins on conflict with class declarations.
+        #
+        # @param dsl_options [Hash] { idempotent: true, idempotency_key: :tx_id, idempotency_ttl: 3600 }
+        # @param tool_class [Class, nil] Tool class for fallback values
+        # @return [Config]
+        def self.from_dsl(dsl_options, tool_class: nil)
+          base = tool_class ? from_tool_class(tool_class) : new
+
+          new(
+            enabled: dsl_options.fetch(:idempotent, base.enabled),
+            key_params: normalize_key_params(dsl_options.fetch(:idempotency_key, base.key_params)),
+            ttl: dsl_options.fetch(:idempotency_ttl, base.ttl),
+            key_fn: dsl_options.fetch(:idempotency_key_fn, base.key_fn),
+          )
+        end
+
+        def self.normalize_key_params(value)
+          case value
+          when Symbol then [value]
+          when Array then value
+          when nil then nil
+          else [value]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/tools/permissions.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Spurline
+  module Tools
+    # Loads tool permissions from a YAML file.
+    # Expected format:
+    #
+    #   tools:
+    #     web_search:
+    #       denied: false
+    #       allowed_users:
+    #         - admin
+    #         - researcher
+    #       requires_confirmation: true
+    #     dangerous_tool:
+    #       denied: true
+    #
+    # Returns a hash keyed by tool name symbols.
+    class Permissions
+      def self.load_file(path)
+        return {} unless path && File.exist?(path)
+
+        raw = YAML.safe_load_file(path, permitted_classes: [Symbol]) || {}
+        tools = raw["tools"] || raw[:tools] || {}
+
+        tools.each_with_object({}) do |(name, config), result|
+          result[name.to_sym] = symbolize_config(config)
+        end
+      end
+
+      def self.symbolize_config(config)
+        return {} unless config.is_a?(Hash)
+
+        config.each_with_object({}) do |(key, value), result|
+          result[key.to_sym] = value
+        end
+      end
+
+      private_class_method :symbolize_config
+    end
+  end
+end

data/lib/spurline/tools/registry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Tools
+    # Global registry of available tools. Tools register themselves here,
+    # either directly or via spur gem auto-registration.
+    class Registry
+      def initialize
+        @tools = {}
+      end
+
+      def register(name, tool_class)
+        name = name.to_sym
+        @tools[name] = tool_class
+      end
+
+      def fetch(name)
+        name = name.to_sym
+        @tools.fetch(name) do
+          raise Spurline::ToolNotFoundError,
+            "Tool '#{name}' is not registered. Ensure its spur gem is installed " \
+            "and required, or register it manually with Spurline::Tools::Registry#register."
+        end
+      end
+
+      def registered?(name)
+        @tools.key?(name.to_sym)
+      end
+
+      def all
+        @tools.dup
+      end
+
+      def names
+        @tools.keys
+      end
+
+      def clear!
+        @tools.clear
+      end
+    end
+  end
+end