spurline-deploy 0.3.0

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

data/lib/spurline/toolkit.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Spurline
+  # A named group of tools with optional shared configuration.
+  # Toolkits own their tools — tools register through their toolkit,
+  # not independently. Tools remain leaf nodes (ADR-003).
+  #
+  # Three patterns for adding tools:
+  #
+  #   # Pattern 1: External class (complex tools in their own file)
+  #   class GitToolkit < Spurline::Toolkit
+  #     toolkit_name :git
+  #     tool GitCommit
+  #     tool GitChangedFiles
+  #     shared_config scoped: true
+  #   end
+  #
+  #   # Pattern 2: Inline definition (small tools)
+  #   class CommsToolkit < Spurline::Toolkit
+  #     toolkit_name :comms
+  #     tool :send_message do
+  #       description "Send a Teams message"
+  #       parameters(type: "object", properties: { text: { type: "string" } })
+  #       def call(text:)
+  #         # implementation
+  #       end
+  #     end
+  #   end
+  #
+  #   # Pattern 3: Standalone tools (one-offs, no toolkit)
+  #   # Register directly via tool_registry.register(:name, ToolClass)
+  #
+  class Toolkit
+    class << self
+      # Set or get the toolkit name. Inferred from class name if not set.
+      def toolkit_name(name = nil)
+        if name
+          @toolkit_name = name.to_sym
+        else
+          @toolkit_name || infer_name
+        end
+      end
+
+      # Register a tool in this toolkit.
+      #
+      # External class:
+      #   tool GitCommit
+      #
+      # Inline definition:
+      #   tool :send_message do
+      #     description "..."
+      #     parameters(...)
+      #     def call(...); end
+      #   end
+      def tool(tool_class_or_name = nil, &block)
+        @tool_entries ||= []
+
+        if block
+          name = tool_class_or_name.to_sym
+          klass = Class.new(Spurline::Tools::Base) do
+            tool_name name
+          end
+          klass.class_eval(&block)
+          @tool_entries << { name: name, tool_class: klass }
+        else
+          klass = tool_class_or_name
+          raise Spurline::ConfigurationError,
+            "Toolkit :#{toolkit_name} — `tool` expects a Tool class or a name with a block. " \
+            "Got: #{klass.inspect}" unless klass.is_a?(Class) && klass < Spurline::Tools::Base
+
+          @tool_entries << { name: klass.tool_name, tool_class: klass }
+        end
+      end
+
+      # Returns tool name symbols for all tools in this toolkit.
+      def tools
+        (@tool_entries || []).map { |e| e[:name] }
+      end
+
+      # Returns { name => ToolClass } for registration into a tool registry.
+      def tool_classes
+        (@tool_entries || []).each_with_object({}) { |e, h| h[e[:name]] = e[:tool_class] }
+      end
+
+      # Shared configuration applied to every tool when this toolkit is
+      # included in an agent. Supports the same keys as per-tool config:
+      # requires_confirmation, scoped, timeout, denied, allowed_users.
+      def shared_config(**opts)
+        if opts.any?
+          @shared_config ||= {}
+          @shared_config.merge!(opts)
+        end
+        @shared_config&.dup || {}
+      end
+
+      private
+
+      def infer_name
+        short = name&.split("::")&.last
+        return :unnamed unless short
+
+        short
+          .gsub(/Toolkit$/, "")
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+          .to_sym
+      end
+    end
+  end
+end