spurline-core 0.3.0

data/lib/spurline/spur.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Spurline
+  # Base class for spur gems. Spur gems are standard Ruby gems that self-register
+  # tools and permissions into the Spurline framework on require.
+  #
+  # The spur contract is locked — this interface cannot change after ship.
+  #
+  # Usage in a spur gem (e.g., spurline-web):
+  #
+  #   module SpurlineWeb
+  #     class Railtie < Spurline::Spur
+  #       spur_name "spurline-web"
+  #
+  #       tools do
+  #         register :web_search, SpurlineWeb::Tools::WebSearch
+  #         register :scrape,     SpurlineWeb::Tools::Scraper
+  #       end
+  #
+  #       permissions do
+  #         default_trust :external
+  #         requires_confirmation false
+  #       end
+  #     end
+  #   end
+  #
+  class Spur
+    class << self
+      # Track all registered spurs for introspection.
+      def registry
+        @registry ||= {}
+      end
+
+      # Tool registrations deferred because Agent wasn't loaded yet.
+      def pending_registrations
+        @pending_registrations ||= []
+      end
+
+      # Adapter registrations deferred because Agent wasn't loaded yet.
+      def pending_adapter_registrations
+        @pending_adapter_registrations ||= []
+      end
+
+      # Replay deferred tool registrations into the given tool registry.
+      def flush_pending_registrations!(registry)
+        return if pending_registrations.empty?
+
+        pending_registrations.each do |registration|
+          registry.register(registration[:name], registration[:tool_class])
+        end
+        pending_registrations.clear
+      end
+
+      # Replay deferred adapter registrations into the given adapter registry.
+      def flush_pending_adapter_registrations!(registry)
+        return if pending_adapter_registrations.empty?
+
+        pending_adapter_registrations.each do |registration|
+          registry.register(registration[:name], registration[:adapter_class])
+        end
+        pending_adapter_registrations.clear
+      end
+
+      # Called by subclasses to set the spur gem name.
+      def spur_name(name = nil)
+        if name
+          @spur_name = name
+        else
+          @spur_name || self.name
+        end
+      end
+
+      # DSL block for registering tools.
+      def tools(&block)
+        @tool_registrations ||= []
+        if block
+          context = ToolRegistrationContext.new
+          context.instance_eval(&block)
+          @tool_registrations = context.registrations
+        end
+        @tool_registrations
+      end
+
+      # DSL block for registering adapters.
+      def adapters(&block)
+        @adapter_registrations ||= []
+        if block
+          context = AdapterRegistrationContext.new
+          context.instance_eval(&block)
+          @adapter_registrations = context.registrations
+        end
+        @adapter_registrations
+      end
+
+      # DSL block for declaring default permissions.
+      def permissions(&block)
+        @permission_defaults ||= {}
+        if block
+          context = PermissionContext.new
+          context.instance_eval(&block)
+          @permission_defaults = context.settings
+        end
+        @permission_defaults
+      end
+
+      # Hook called when a subclass is defined. Auto-registers the spur.
+      def inherited(subclass)
+        super
+        # Defer registration to allow the class body to execute first.
+        TracePoint.new(:end) do |tp|
+          if tp.self == subclass
+            tp.disable
+            subclass.send(:auto_register!)
+          end
+        end.enable
+      end
+
+      private
+
+      # Auto-registers this spur's tools and adapters into the global
+      # Spurline::Agent registries. If Agent hasn't been loaded yet (Zeitwerk
+      # lazy loading), the registrations are deferred and replayed when the
+      # respective registry is first accessed.
+      def auto_register!
+        Spur.registry[spur_name] = {
+          tools: tools.map { |r| r[:name] },
+          adapters: adapters.map { |r| r[:name] },
+          permissions: permissions,
+        }
+
+        register_tools!
+        register_adapters!
+      end
+
+      def register_tools!
+        return if tools.empty?
+
+        if defined?(Spurline::Agent) && Spurline::Agent.respond_to?(:tool_registry)
+          tools.each do |registration|
+            Spurline::Agent.tool_registry.register(
+              registration[:name],
+              registration[:tool_class]
+            )
+          end
+        else
+          Spur.pending_registrations.concat(tools)
+        end
+      end
+
+      def register_adapters!
+        return if adapters.empty?
+
+        if defined?(Spurline::Agent) && Spurline::Agent.respond_to?(:adapter_registry)
+          adapters.each do |registration|
+            Spurline::Agent.adapter_registry.register(
+              registration[:name],
+              registration[:adapter_class]
+            )
+          end
+        else
+          Spur.pending_adapter_registrations.concat(adapters)
+        end
+      end
+    end
+
+    # Context object for the `tools` DSL block.
+    class ToolRegistrationContext
+      attr_reader :registrations
+
+      def initialize
+        @registrations = []
+      end
+
+      def register(name, tool_class)
+        @registrations << { name: name.to_sym, tool_class: tool_class }
+      end
+    end
+
+    # Context object for the `adapters` DSL block.
+    class AdapterRegistrationContext
+      attr_reader :registrations
+
+      def initialize
+        @registrations = []
+      end
+
+      def register(name, adapter_class)
+        @registrations << { name: name.to_sym, adapter_class: adapter_class }
+      end
+    end
+
+    # Context object for the `permissions` DSL block.
+    class PermissionContext
+      attr_reader :settings
+
+      def initialize
+        @settings = {}
+      end
+
+      def default_trust(level)
+        @settings[:default_trust] = level
+      end
+
+      def requires_confirmation(val = true)
+        @settings[:requires_confirmation] = val
+      end
+
+      def sandbox(val = true)
+        @settings[:sandbox] = val
+      end
+    end
+  end
+end

data/lib/spurline/streaming/CLAUDE.md

@@ -0,0 +1,12 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3631 | 6:00 PM | ⚖️ | Long-term memory architecture with pgvector and OpenAI embeddings | ~501 |
+| #3632 | " | ⚖️ | OpenAI adapter architecture with stop reason normalization and tool call accumulation | ~541 |
+</claude-mem-context>

data/lib/spurline/streaming/buffer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Streaming
+    # Accumulates streaming chunks to detect tool call boundaries.
+    # Text chunks are yielded immediately to the caller.
+    # Tool calls are only dispatched when the full argument payload has arrived.
+    #
+    # Handles edge cases:
+    # - Multiple tool calls in a single response
+    # - Partial JSON arguments across chunks
+    # - Mixed text and tool call responses
+    class Buffer
+      attr_reader :chunks
+
+      def initialize
+        @chunks = []
+        @stop_reason = nil
+      end
+
+      def <<(chunk)
+        @chunks << chunk
+        @stop_reason = chunk.metadata[:stop_reason] if chunk.done?
+        self
+      end
+
+      def complete?
+        @chunks.any?(&:done?)
+      end
+
+      def tool_call?
+        @stop_reason == "tool_use"
+      end
+
+      def text_chunks
+        @chunks.select(&:text?)
+      end
+
+      def full_text
+        text_chunks.map(&:text).join
+      end
+
+      # Returns all tool call data from metadata.
+      # Supports multiple tool calls in a single response.
+      def tool_calls
+        calls = @chunks
+          .select { |c| c.metadata[:tool_call] }
+          .map { |c| c.metadata[:tool_call] }
+
+        # Deduplicate by name+arguments (guards against duplicate chunk delivery)
+        calls.uniq { |c| [c[:name], c[:arguments]] }
+      end
+
+      def tool_call_count
+        tool_calls.length
+      end
+
+      # The stop reason from the done chunk.
+      def stop_reason
+        @stop_reason
+      end
+
+      def clear!
+        @chunks = []
+        @stop_reason = nil
+      end
+
+      def size
+        @chunks.length
+      end
+
+      def empty?
+        @chunks.empty?
+      end
+    end
+  end
+end

data/lib/spurline/streaming/chunk.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Streaming
+    # A typed chunk of streaming output. Never a raw string.
+    #
+    # Types:
+    #   :text       — text content from the LLM
+    #   :tool_start — a tool execution is beginning
+    #   :tool_end   — a tool execution has completed
+    #   :done       — the stream is complete
+    class Chunk
+      TYPES = %i[text tool_start tool_end done].freeze
+
+      attr_reader :type, :text, :turn, :session_id, :metadata
+
+      def initialize(type:, text: nil, turn: nil, session_id: nil, metadata: {})
+        validate_type!(type)
+
+        @type = type
+        @text = text&.dup&.freeze
+        @turn = turn
+        @session_id = session_id
+        @metadata = metadata.freeze
+        freeze
+      end
+
+      def text?
+        type == :text
+      end
+
+      def tool_start?
+        type == :tool_start
+      end
+
+      def tool_end?
+        type == :tool_end
+      end
+
+      def done?
+        type == :done
+      end
+
+      def inspect
+        parts = ["type=#{type}"]
+        parts << "text=#{text[0..30].inspect}#{text.length > 30 ? "..." : ""}" if text
+        parts << "turn=#{turn}" if turn
+        "#<Spurline::Streaming::Chunk #{parts.join(" ")}>"
+      end
+
+      private
+
+      def validate_type!(type)
+        return if TYPES.include?(type)
+
+        raise Spurline::ConfigurationError,
+          "Invalid chunk type: #{type.inspect}. " \
+          "Must be one of: #{TYPES.map(&:inspect).join(", ")}."
+      end
+    end
+  end
+end

data/lib/spurline/streaming/stream_enumerator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Streaming
+    # Wraps a block-based streaming interface into a Ruby Enumerator.
+    # This allows both block and enumerator usage patterns (ADR-001):
+    #
+    #   agent.run("hello") { |chunk| print chunk.text }
+    #   agent.run("hello").each { |chunk| print chunk.text }
+    #
+    class StreamEnumerator
+      include Enumerable
+
+      def initialize(&producer)
+        @producer = producer
+      end
+
+      def each(&consumer)
+        if consumer
+          @producer.call(consumer)
+        else
+          ::Enumerator.new do |yielder|
+            @producer.call(proc { |chunk| yielder << chunk })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/testing.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Spurline
+  # Test helpers for Spurline agents. Require in your spec_helper:
+  #
+  #   require "spurline/testing"
+  #
+  # Then include in your specs:
+  #
+  #   include Spurline::Testing
+  #
+  # Or let the auto-configuration handle it (included globally if RSpec is loaded).
+  module Testing
+    TOOL_SOURCE_PATTERN = /source=["']tool:(?<tool_name>[^"']+)["']/.freeze
+
+    # Creates a stub text response that streams as chunks.
+    def stub_text(text, turn: 1)
+      chunks = text.chars.each_slice(5).map do |chars|
+        Spurline::Streaming::Chunk.new(
+          type: :text,
+          text: chars.join,
+          turn: turn
+        )
+      end
+
+      chunks << Spurline::Streaming::Chunk.new(
+        type: :done,
+        turn: turn,
+        metadata: { stop_reason: "end_turn" }
+      )
+
+      { type: :text, text: text, chunks: chunks }
+    end
+
+    # Creates a stub tool call response.
+    def stub_tool_call(tool_name, turn: 1, **arguments)
+      tool_call_data = { name: tool_name.to_s, arguments: arguments }
+
+      chunks = [
+        Spurline::Streaming::Chunk.new(
+          type: :tool_start,
+          turn: turn,
+          metadata: { tool_name: tool_name.to_s, arguments: arguments }
+        ),
+        Spurline::Streaming::Chunk.new(
+          type: :done,
+          turn: turn,
+          metadata: {
+            stop_reason: "tool_use",
+            tool_call: tool_call_data,
+          }
+        ),
+      ]
+
+      { type: :tool_call, tool_call: tool_call_data, chunks: chunks }
+    end
+
+    # Asserts that a tool was called, optionally with matching arguments.
+    #
+    # Sources checked in order:
+    #   1) audit_log tool_call events
+    #   2) session turn tool_calls
+    #   3) StubAdapter call history (tool presence only)
+    #
+    # @param tool_name [Symbol, String]
+    # @param with [Hash] expected argument subset
+    # @param agent [Spurline::Agent, nil]
+    # @param adapter [Spurline::Adapters::StubAdapter, nil]
+    # @param audit_log [Spurline::Audit::Log, nil]
+    # @param session [Spurline::Session::Session, nil]
+    # @return [true]
+    def assert_tool_called(tool_name, with: {}, agent: nil, adapter: nil, audit_log: nil, session: nil)
+      tool = tool_name.to_s
+      expected_arguments = deep_symbolize(with || {})
+      audit_entries, session_entries, adapter_instance = resolve_tool_call_sources(
+        agent: agent,
+        adapter: adapter,
+        audit_log: audit_log,
+        session: session
+      )
+
+      matched = match_tool_call(tool, expected_arguments, audit_entries, key: :tool) ||
+                match_tool_call(tool, expected_arguments, session_entries, key: :name)
+      return true if matched
+
+      if tool_called_in_history?(tool, audit_entries, key: :tool) ||
+         tool_called_in_history?(tool, session_entries, key: :name)
+        raise_expectation!(
+          "Expected tool '#{tool}' to be called#{format_expected_arguments(expected_arguments)}."
+        )
+      end
+
+      if tool_called_in_adapter_history?(adapter_instance, tool)
+        if expected_arguments.empty?
+          return true
+        end
+
+        raise_expectation!(
+          "Tool '#{tool}' was detected in StubAdapter call history, but argument assertions " \
+          "require session or audit history. Pass `agent:`, `session:`, or `audit_log:`."
+        )
+      end
+
+      raise_expectation!(
+        "Expected tool '#{tool}' to be called#{format_expected_arguments(expected_arguments)}."
+      )
+    end
+
+    # Asserts that no injection detection error is raised while evaluating the block.
+    #
+    # @yield A call that runs through the context pipeline.
+    # @return [true]
+    def expect_no_injection
+      raise ArgumentError, "expect_no_injection requires a block" unless block_given?
+
+      yield
+      true
+    rescue *injection_error_classes => e
+      raise_expectation!(
+        "Expected no injection detection errors, but #{e.class.name} was raised: #{e.message}"
+      )
+    end
+
+    # Asserts that a Content object carries the expected trust level.
+    #
+    # @param content [Spurline::Security::Content]
+    # @param expected_trust [Symbol, String]
+    # @return [true]
+    def assert_trust_level(content, expected_trust)
+      unless content.is_a?(Spurline::Security::Content)
+        raise_expectation!(
+          "Expected Spurline::Security::Content, got #{content.class.name}."
+        )
+      end
+
+      expected = expected_trust.to_sym
+      actual = content.trust
+      return true if actual == expected
+
+      raise_expectation!("Expected trust level #{expected.inspect}, got #{actual.inspect}.")
+    end
+
+    private
+
+    def resolve_tool_call_sources(agent:, adapter:, audit_log:, session:)
+      audit = audit_log
+      sess = session
+      adapter_instance = adapter
+
+      if agent
+        audit ||= agent.respond_to?(:audit_log) ? agent.audit_log : nil
+        sess ||= agent.respond_to?(:session) ? agent.session : nil
+        if adapter_instance.nil? && agent.instance_variable_defined?(:@adapter)
+          adapter_instance = agent.instance_variable_get(:@adapter)
+        end
+      end
+
+      audit_entries = audit.respond_to?(:tool_calls) ? audit.tool_calls : []
+      session_entries = sess.respond_to?(:tool_calls) ? sess.tool_calls : []
+
+      [audit_entries, session_entries, adapter_instance]
+    end
+
+    def match_tool_call(tool, expected_arguments, entries, key:)
+      entries.find do |entry|
+        next false unless entry[key].to_s == tool
+
+        actual_arguments = deep_symbolize(entry[:arguments] || {})
+        hash_subset?(actual_arguments, expected_arguments)
+      end
+    end
+
+    def tool_called_in_history?(tool, entries, key:)
+      entries.any? { |entry| entry[key].to_s == tool }
+    end
+
+    def tool_called_in_adapter_history?(adapter, tool)
+      return false unless adapter.respond_to?(:calls)
+
+      adapter.calls.any? do |call|
+        messages = Array(call[:messages])
+        messages.any? do |message|
+          content = message[:content].to_s
+          match = TOOL_SOURCE_PATTERN.match(content)
+          match && match[:tool_name] == tool
+        end
+      end
+    end
+
+    def hash_subset?(actual, expected)
+      return true if expected.empty?
+      return false unless actual.is_a?(Hash)
+
+      expected.all? do |key, value|
+        actual_value = actual[key]
+        if value.is_a?(Hash)
+          hash_subset?(actual_value, value)
+        else
+          actual_value == value
+        end
+      end
+    end
+
+    def deep_symbolize(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested), hash|
+          hash[key.to_sym] = deep_symbolize(nested)
+        end
+      when Array
+        value.map { |item| deep_symbolize(item) }
+      else
+        value
+      end
+    end
+
+    def format_expected_arguments(arguments)
+      return "" if arguments.empty?
+
+      " with arguments #{arguments.inspect}"
+    end
+
+    def injection_error_classes
+      classes = []
+      classes << Spurline::InjectionAttemptError if defined?(Spurline::InjectionAttemptError)
+      classes << Spurline::InjectionDetectedError if defined?(Spurline::InjectionDetectedError)
+      classes
+    end
+
+    def raise_expectation!(message)
+      if defined?(RSpec::Expectations::ExpectationNotMetError)
+        raise RSpec::Expectations::ExpectationNotMetError, message
+      end
+
+      raise RuntimeError, message
+    end
+  end
+end
+
+# Auto-include in RSpec if available
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include Spurline::Testing
+  end
+end