spurline-test 0.3.0

data/lib/spurline/agent.rb

@@ -0,0 +1,433 @@
+# frozen_string_literal: true
+
+require_relative "lifecycle/suspension_boundary"
+
+module Spurline
+  # The public API for Spurline agents. Developers inherit from this class.
+  #
+  #   class ResearchAgent < Spurline::Agent
+  #     use_model :claude_sonnet
+  #     persona(:default) { system_prompt "You are a research assistant." }
+  #     tools :web_search
+  #     guardrails { max_tool_calls 5 }
+  #   end
+  #
+  #   agent = ResearchAgent.new
+  #   agent.run("Research competitors") { |chunk| print chunk.text }
+  #
+  class Agent < Base
+    attr_reader :session, :state, :audit_log, :vault
+
+    def initialize(user: nil, session_id: nil, persona: :default, scope: nil, **opts)
+      @user = user
+      @session = Session::Session.load_or_create(
+        id: session_id,
+        store: self.class.session_store,
+        agent_class: self.class.name,
+        user: user
+      )
+      @scope = scope
+      @idempotency_ledger = @session.metadata[:idempotency_ledger] ||= {}
+      @persona = resolve_persona(persona)
+      @memory = Memory::Manager.new(config: self.class.memory_config)
+      @vault = Secrets::Vault.new
+
+      secret_resolver = Secrets::Resolver.new(
+        vault: @vault,
+        overrides: resolve_secret_overrides
+      )
+
+      @tool_runner = Tools::Runner.new(
+        registry: self.class.tool_registry,
+        guardrails: guardrail_settings,
+        permissions: self.class.respond_to?(:permissions_config) ? self.class.permissions_config : {},
+        secret_resolver: secret_resolver,
+        idempotency_configs: self.class.respond_to?(:idempotency_config) ? self.class.idempotency_config : {}
+      )
+      @pipeline = Security::ContextPipeline.new(guardrails: guardrail_settings)
+      @adapter = resolve_adapter
+      @audit_log = Audit::Log.new(
+        session: @session,
+        registry: self.class.tool_registry,
+        max_entries: resolve_audit_max_entries
+      )
+      @assembler = Memory::ContextAssembler.new
+      @state = @session.respond_to?(:suspended?) && @session.suspended? ? :suspended : :ready
+
+      # Restore memory from existing session if resuming
+      restore_session_memory!
+
+      run_hook(:on_start, @session)
+    end
+
+    # Single-shot execution. Streams chunks via block or returns an Enumerator (ADR-001).
+    def run(input, suspension_check: nil, mode: :normal, tool_sequence: nil, &block)
+      if block
+        execute_run(
+          input,
+          suspension_check: suspension_check,
+          mode: mode,
+          tool_sequence: tool_sequence,
+          &block
+        )
+      else
+        Streaming::StreamEnumerator.new do |consumer|
+          execute_run(
+            input,
+            suspension_check: suspension_check,
+            mode: mode,
+            tool_sequence: tool_sequence
+          ) { |chunk| consumer.call(chunk) }
+        end
+      end
+    end
+
+    # Multi-turn conversation. Session persists between calls.
+    # Resets agent state between turns to allow consecutive calls.
+    def chat(input, suspension_check: nil, mode: :normal, tool_sequence: nil, &block)
+      reset_for_next_turn! if @state == :complete
+
+      if block
+        execute_run(
+          input,
+          suspension_check: suspension_check,
+          mode: mode,
+          tool_sequence: tool_sequence,
+          &block
+        )
+      else
+        Streaming::StreamEnumerator.new do |consumer|
+          execute_run(
+            input,
+            suspension_check: suspension_check,
+            mode: mode,
+            tool_sequence: tool_sequence
+          ) { |chunk| consumer.call(chunk) }
+        end
+      end
+    end
+
+    # Resume a suspended session from its last checkpoint.
+    def resume(suspension_check: nil, &block)
+      unless @session.suspended?
+        raise Spurline::InvalidResumeError,
+          "Session is not suspended (state=#{@session.state.inspect})"
+      end
+
+      checkpoint = Session::Suspension.checkpoint_for(@session)
+      input = resume_input_from_checkpoint(checkpoint)
+
+      if block
+        execute_run(
+          input,
+          suspension_check: suspension_check,
+          resume_checkpoint: checkpoint,
+          &block
+        )
+      else
+        Streaming::StreamEnumerator.new do |consumer|
+          execute_run(
+            input,
+            suspension_check: suspension_check,
+            resume_checkpoint: checkpoint
+          ) { |chunk| consumer.call(chunk) }
+        end
+      end
+    end
+
+    # Test helper — swap the adapter for a stub.
+    def use_stub_adapter(responses: [])
+      @adapter = Adapters::StubAdapter.new(responses: responses)
+    end
+
+    # Spawn a child agent with inherited permissions and scope (ADR-005).
+    # The child runs in its own session and streams chunks to the provided block.
+    # Returns the child's session.
+    #
+    # @param agent_class [Class] A class that inherits from Spurline::Agent
+    # @param input [String] The input to pass to the child agent's #run
+    # @param permissions [Hash, nil] Optional permission overrides (must be <= parent)
+    # @param scope [Spurline::Tools::Scope, Hash, nil] Optional scope override (must be <= parent)
+    # @return [Spurline::Session::Session] The child agent's completed session
+    def spawn_agent(agent_class, input:, permissions: nil, scope: nil, &block)
+      spawner = Orchestration::AgentSpawner.new(parent_agent: self)
+      spawner.spawn(agent_class, input: input, permissions: permissions, scope: scope, &block)
+    end
+
+    # Structured per-session event trace.
+    def episodes
+      @memory.episodic
+    end
+
+    # Human-readable narrative of the episodic trace.
+    def explain
+      episodes.explain
+    end
+
+    private
+
+    def execute_run(
+      input,
+      suspension_check: nil,
+      resume_checkpoint: nil,
+      mode: :normal,
+      tool_sequence: nil,
+      &chunk_handler
+    )
+      if @session.suspended? && resume_checkpoint.nil?
+        raise Spurline::InvalidResumeError,
+          "Session is suspended. Use #resume to continue from checkpoint."
+      end
+
+      if mode == :deterministic
+        return execute_deterministic_run(input, tool_sequence: tool_sequence, &chunk_handler)
+      end
+
+      wrapped_input = resume_checkpoint ? input : wrap_input(input)
+      @state = :running
+      if resume_checkpoint
+        @session.resume!
+        run_hook(:on_resume, @session, resume_checkpoint)
+      else
+        @session.transition_to!(:running)
+        run_hook(:on_turn_start, @session)
+      end
+
+      runner = Lifecycle::Runner.new(
+        adapter: @adapter,
+        pipeline: @pipeline,
+        tool_runner: @tool_runner,
+        memory: @memory,
+        assembler: @assembler,
+        audit: @audit_log,
+        guardrails: guardrail_settings,
+        suspension_check: effective_suspension_check(suspension_check),
+        scope: @scope,
+        idempotency_ledger: @idempotency_ledger
+      )
+
+      runner.run(
+        input: wrapped_input,
+        session: @session,
+        persona: @persona,
+        tools_schema: build_tools_schema,
+        adapter_config: self.class.model_config || {},
+        agent_context: build_agent_context,
+        resume_checkpoint: resume_checkpoint
+      ) do |chunk|
+        run_hook(:on_tool_call, chunk.metadata, @session) if chunk.tool_end?
+        chunk_handler&.call(chunk)
+      end
+
+      @state = :complete
+      @session.complete!
+      run_hook(:on_turn_end, @session, @session.current_turn)
+      run_hook(:on_finish, @session)
+    rescue Spurline::Lifecycle::SuspensionSignal => e
+      @state = :suspended
+      @session.suspend!(checkpoint: e.checkpoint)
+      @audit_log.record(:suspended, turn: @session.current_turn&.number)
+      run_hook(:on_suspend, @session, e.checkpoint)
+      nil
+    rescue Spurline::InvalidResumeError
+      raise
+    rescue Spurline::AgentError => e
+      @state = :error
+      @session.error!(e)
+      @audit_log.record(:error, error: e.class.name, message: e.message)
+      run_hook(:on_error, e)
+      raise
+    end
+
+    def execute_deterministic_run(input, tool_sequence: nil, &chunk_handler)
+      sequence = tool_sequence || self.class.deterministic_sequence_config
+      if sequence.nil? || sequence.empty?
+        raise Spurline::ConfigurationError,
+          "No deterministic tool sequence configured. " \
+          "Declare one with `deterministic_sequence :tool1, :tool2` in the agent class, " \
+          "or pass `tool_sequence:` to #run."
+      end
+
+      wrapped_input = wrap_input(input)
+      @state = :running
+      @session.transition_to!(:running)
+      run_hook(:on_turn_start, @session)
+
+      det_runner = Lifecycle::DeterministicRunner.new(
+        tool_runner: @tool_runner,
+        audit_log: @audit_log,
+        session: @session,
+        guardrails: guardrail_settings,
+        scope: @scope,
+        idempotency_ledger: @idempotency_ledger
+      )
+
+      det_runner.run(
+        tool_sequence: sequence,
+        input: wrapped_input,
+        session: @session
+      ) do |chunk|
+        run_hook(:on_tool_call, chunk.metadata, @session) if chunk.tool_end?
+        chunk_handler&.call(chunk)
+      end
+
+      @memory.add_turn(@session.current_turn) if @session.current_turn
+      @state = :complete
+      @session.complete!
+      run_hook(:on_turn_end, @session, @session.current_turn)
+      run_hook(:on_finish, @session)
+    rescue Spurline::AgentError => e
+      @state = :error
+      @session.error!(e)
+      @audit_log.record(:error, error: e.class.name, message: e.message)
+      run_hook(:on_error, e)
+      raise
+    end
+
+    def wrap_input(input)
+      if input.is_a?(Security::Content)
+        input
+      else
+        Security::Gates::UserInput.wrap(input.to_s, user_id: @user.to_s)
+      end
+    end
+
+    def resolve_persona(name)
+      configs = self.class.persona_configs
+      config = configs[name.to_sym]
+      return nil unless config
+
+      Persona::Base.new(
+        name: name,
+        system_prompt: config.system_prompt_text,
+        injection_config: {
+          inject_date: config.date_injected?,
+          inject_user_context: config.user_context_injected?,
+          inject_agent_context: config.agent_context_injected?,
+        }
+      )
+    end
+
+    def resolve_adapter
+      config = self.class.model_config
+      return nil unless config
+
+      begin
+        adapter_class = self.class.adapter_registry.resolve(config[:name])
+        return adapter_class unless adapter_class.is_a?(Class)
+
+        # Build adapter kwargs from DEFAULT_ADAPTERS defaults + use_model kwargs.
+        # use_model kwargs (host:, port:, model:, options:, etc.) take precedence.
+        adapter_kwargs = {}
+        defaults = Base::DEFAULT_ADAPTERS[config[:name]]
+        adapter_kwargs[:model] = defaults[:model] if defaults && defaults[:model]
+
+        # Forward all use_model kwargs except :name (which is the adapter selector)
+        # and per-call API params like :tool_choice that belong in stream config, not constructor.
+        user_kwargs = config.reject { |k, _| %i[name tool_choice].include?(k) }
+        adapter_kwargs.merge!(user_kwargs)
+
+        adapter_kwargs.empty? ? adapter_class.new : adapter_class.new(**adapter_kwargs)
+      rescue Spurline::AdapterNotFoundError
+        # Adapter not yet registered — allows use_stub_adapter to set it later.
+        nil
+      end
+    end
+
+    def guardrail_settings
+      gc = self.class.guardrail_config
+      gc.respond_to?(:to_h) ? gc.to_h : gc.settings
+    end
+
+    def resolve_audit_max_entries
+      settings = guardrail_settings
+      guardrail_limit = settings[:audit_max_entries]
+      return guardrail_limit unless guardrail_limit.nil?
+
+      Spurline.config.audit_max_entries
+    end
+
+    def build_tools_schema
+      tool_config = self.class.tool_config
+      return [] unless tool_config
+
+      tool_config[:names].map do |name|
+        tool_class = self.class.tool_registry.fetch(name)
+        tool = tool_class.is_a?(Class) ? tool_class.new : tool_class
+        tool.to_schema
+      end
+    end
+
+    def build_agent_context
+      tool_config = self.class.tool_config
+      tool_names = tool_config ? tool_config[:names] : []
+
+      {
+        class_name: self.class.name || self.class.to_s,
+        tool_names: tool_names.map(&:to_s),
+      }
+    end
+
+    def run_hook(hook_type, *args)
+      hooks = self.class.hooks_config[hook_type] || []
+      hooks.each { |block| block.call(*args) }
+    end
+
+    def effective_suspension_check(suspension_check)
+      return suspension_check if suspension_check
+      return self.class.build_suspension_check if self.class.respond_to?(:build_suspension_check)
+
+      Lifecycle::SuspensionCheck.none
+    end
+
+    def resolve_secret_overrides
+      overrides = {}
+      tool_config = self.class.tool_config
+      return overrides unless tool_config
+
+      tool_config[:configs].each do |_tool_name, config|
+        next unless config.is_a?(Hash)
+
+        secrets = config[:secrets] || config["secrets"]
+        next unless secrets.is_a?(Hash)
+
+        secrets.each do |key, value|
+          overrides[key.to_sym] = value
+        end
+      end
+
+      overrides
+    end
+
+    def restore_session_memory!
+      @memory.restore_episodes(@session.metadata[:episodes] || [])
+      return unless @session.turns.any?(&:complete?)
+
+      resumption = Session::Resumption.new(session: @session, memory: @memory)
+      resumption.restore!
+    end
+
+    def resume_input_from_checkpoint(checkpoint)
+      serialized = checkpoint_value(checkpoint, :last_tool_result)
+      if serialized && !serialized.to_s.empty?
+        Security::Gates::ToolResult.wrap(serialized.to_s, tool_name: "suspended_resume")
+      elsif @session.current_turn
+        @session.current_turn.input
+      else
+        Security::Gates::UserInput.wrap("", user_id: @user.to_s)
+      end
+    end
+
+    def checkpoint_value(checkpoint, key)
+      return nil unless checkpoint
+
+      checkpoint[key] || checkpoint[key.to_s]
+    end
+
+    def reset_for_next_turn!
+      @state = :ready
+      # Session state stays as-is — load_or_create handles resumption.
+      # We just need to allow the agent to run again.
+    end
+  end
+end

data/lib/spurline/audit/log.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Audit
+    # Records structured events for a session. All entries are flat records (ADR-003).
+    #
+    # Event types:
+    #   :turn_start       — A new turn begins
+    #   :turn_end         — A turn completes
+    #   :llm_request      — Outbound LLM request shape
+    #   :llm_response     — Inbound LLM response shape
+    #   :tool_call        — A tool was invoked
+    #   :tool_result      — A tool returned a result
+    #   :error            — An error occurred
+    #   :injection_blocked — Injection attempt detected and blocked
+    #   :pii_detected     — PII was detected (mode-dependent behavior)
+    #   :max_tool_calls_reached — Tool call limit was hit
+    #   :session_complete  — Session finished
+    #   :session_error     — Session errored
+    class Log
+      KNOWN_EVENTS = %i[
+        turn_start turn_end
+        llm_request llm_response
+        tool_call tool_result
+        error
+        injection_blocked pii_detected
+        max_tool_calls_reached
+        session_complete session_error
+      ].freeze
+
+      attr_reader :entries, :evicted_count
+
+      def initialize(session:, registry: nil, max_entries: nil)
+        @session = session
+        @registry = registry
+        @max_entries = max_entries
+        @entries = []
+        @evicted_count = 0
+        @started_at = Time.now
+      end
+
+      def record(event_type, data = {})
+        event = event_type.to_sym
+        record_data = maybe_filter_tool_arguments(event, data)
+
+        entry = {
+          event: event,
+          timestamp: Time.now,
+          session_id: @session.id,
+          elapsed_ms: elapsed_ms,
+          **record_data,
+        }
+        @entries << entry
+        evict_if_needed!
+        entry
+      end
+
+      def size
+        @entries.length
+      end
+
+      # Filter entries by event type.
+      def events_of_type(event_type)
+        @entries.select { |e| e[:event] == event_type.to_sym }
+      end
+
+      # All tool call entries.
+      def tool_calls
+        events_of_type(:tool_call)
+      end
+
+      # All error entries.
+      def errors
+        events_of_type(:error)
+      end
+
+      # All llm request entries.
+      def llm_requests
+        events_of_type(:llm_request)
+      end
+
+      # All llm response entries.
+      def llm_responses
+        events_of_type(:llm_response)
+      end
+
+      # All entries for a specific turn.
+      def turn_events(turn_number)
+        @entries.select { |e| e[:turn] == turn_number }
+      end
+
+      # Compact event stream suitable for replay/debugging.
+      def replay_timeline
+        @entries.map do |entry|
+          {
+            event: entry[:event],
+            elapsed_ms: entry[:elapsed_ms],
+            turn: entry[:turn],
+            loop: entry[:loop],
+            tool: entry[:tool],
+          }.compact
+        end
+      end
+
+      # Total duration of all recorded tool calls.
+      def total_tool_duration_ms
+        tool_calls.sum { |tc| tc[:duration_ms] || 0 }
+      end
+
+      # Compact summary of the audit log.
+      def summary
+        {
+          session_id: @session.id,
+          total_events: size + @evicted_count,
+          evicted_entries: @evicted_count,
+          turns: events_of_type(:turn_start).length,
+          tool_calls: tool_calls.length,
+          errors: errors.length,
+          total_tool_duration_ms: total_tool_duration_ms,
+          total_elapsed_ms: elapsed_ms,
+        }
+      end
+
+      private
+
+      def elapsed_ms
+        ((Time.now - @started_at) * 1000).round
+      end
+
+      def maybe_filter_tool_arguments(event_type, data)
+        return data unless event_type == :tool_call
+        return data unless data.is_a?(Hash)
+        return data unless data.key?(:arguments) || data.key?("arguments")
+
+        tool_name = data[:tool] || data["tool"]
+        arguments_key = data.key?(:arguments) ? :arguments : "arguments"
+        filtered_arguments = SecretFilter.filter(
+          data[arguments_key],
+          tool_name: tool_name,
+          registry: @registry
+        )
+        data.merge(arguments_key => filtered_arguments)
+      end
+
+      def evict_if_needed!
+        return unless @max_entries
+        return unless @max_entries.is_a?(Integer) && @max_entries.positive?
+
+        while @entries.length > @max_entries
+          @entries.shift
+          @evicted_count += 1
+        end
+      end
+    end
+  end
+end

data/lib/spurline/audit/secret_filter.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+require "set"
+
+module Spurline
+  module Audit
+    # Stateless redaction utility for tool-call argument payloads.
+    module SecretFilter
+      SENSITIVE_PATTERNS = %w[
+        key token secret password credential passphrase
+        api_key api_secret access_token refresh_token
+        auth bearer jwt private_key
+      ].freeze
+
+      class << self
+        # Returns a filtered copy of arguments with sensitive values redacted.
+        # Never mutates the original object.
+        def filter(arguments, tool_name:, registry: nil)
+          return nil if arguments.nil?
+
+          sensitive_fields = sensitive_parameters_for(tool_name, registry)
+          filter_value(arguments, sensitive_fields)
+        end
+
+        # Returns true when any sensitive key is present in arguments.
+        def contains_secrets?(arguments, tool_name:, registry: nil)
+          return false if arguments.nil?
+
+          sensitive_fields = sensitive_parameters_for(tool_name, registry)
+          contains_secrets_in_value?(arguments, sensitive_fields)
+        end
+
+        private
+
+        def filter_value(value, sensitive_fields)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), out|
+              key_name = key.to_s
+              if sensitive_key?(key_name, sensitive_fields)
+                out[key] = redacted_placeholder(key_name)
+              else
+                out[key] = filter_value(nested, sensitive_fields)
+              end
+            end
+          when Array
+            value.map { |nested| filter_value(nested, sensitive_fields) }
+          else
+            value
+          end
+        end
+
+        def contains_secrets_in_value?(value, sensitive_fields)
+          case value
+          when Hash
+            value.any? do |key, nested|
+              sensitive_key?(key.to_s, sensitive_fields) ||
+                contains_secrets_in_value?(nested, sensitive_fields)
+            end
+          when Array
+            value.any? { |nested| contains_secrets_in_value?(nested, sensitive_fields) }
+          else
+            false
+          end
+        end
+
+        def sensitive_key?(name, sensitive_fields)
+          normalized = normalize_key(name)
+          return true if sensitive_fields.include?(normalized)
+
+          tokens = normalized.split("_")
+          SENSITIVE_PATTERNS.any? do |pattern|
+            pattern_tokens = pattern.split("_")
+            if pattern_tokens.length == 1
+              tokens.include?(pattern)
+            else
+              tokens.each_cons(pattern_tokens.length).any? { |slice| slice == pattern_tokens }
+            end
+          end
+        end
+
+        def sensitive_parameters_for(tool_name, registry)
+          tool = resolve_tool(tool_name, registry)
+          return Set.new unless tool&.respond_to?(:sensitive_parameters)
+
+          raw = tool.sensitive_parameters || Set.new
+          Set.new(raw.map { |name| normalize_key(name) })
+        rescue StandardError
+          Set.new
+        end
+
+        def resolve_tool(tool_name, registry)
+          return nil unless registry && tool_name
+
+          if registry.respond_to?(:registered?) && !registry.registered?(tool_name)
+            return nil
+          end
+
+          tool = registry.fetch(tool_name)
+          return tool.class unless tool.is_a?(Class)
+
+          tool
+        rescue StandardError
+          nil
+        end
+
+        def normalize_key(name)
+          name.to_s
+            .gsub(/([a-z0-9])([A-Z])/, '\1_\2')
+            .strip
+            .downcase
+            .gsub(/[^a-z0-9]+/, "_")
+            .gsub(/\A_+|_+\z/, "")
+        end
+
+        def redacted_placeholder(field_name)
+          "[REDACTED:#{field_name}]"
+        end
+      end
+    end
+  end
+end