spurline-core 0.3.0

data/lib/spurline/adapters/registry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    # Registry of available LLM adapters. Maps symbolic names to adapter classes.
+    class Registry
+      def initialize
+        @adapters = {}
+      end
+
+      def register(name, adapter_class)
+        @adapters[name.to_sym] = adapter_class
+      end
+
+      def resolve(name)
+        name = name.to_sym
+        @adapters.fetch(name) do
+          raise Spurline::AdapterNotFoundError,
+            "Adapter '#{name}' is not registered. Available adapters: " \
+            "#{@adapters.keys.map(&:inspect).join(", ")}."
+        end
+      end
+
+      def registered?(name)
+        @adapters.key?(name.to_sym)
+      end
+
+      def names
+        @adapters.keys
+      end
+    end
+  end
+end

data/lib/spurline/adapters/scheduler/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    module Scheduler
+      # Abstract scheduler interface. The scheduler parameter is the async seam (ADR-002).
+      # v1 ships only Sync. A future async scheduler will implement the same interface.
+      class Base
+        def run(&block)
+          raise NotImplementedError, "#{self.class.name} must implement #run"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/adapters/scheduler/sync.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    module Scheduler
+      # Synchronous no-op scheduler. Simply yields the block.
+      # This is the v1 default — the async seam (ADR-002).
+      class Sync < Base
+        def run(&block)
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/spurline/adapters/stub_adapter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    # Test adapter that plays back canned streaming responses.
+    # Ships with the framework — available in production code for testing and demos.
+    #
+    # Usage:
+    #   adapter = StubAdapter.new(responses: [
+    #     stub_text("Here is what I found..."),
+    #     stub_tool_call(:web_search, query: "test"),
+    #     stub_text("Based on my research...")
+    #   ])
+    class StubAdapter < Base
+      attr_reader :calls
+
+      def initialize(responses: [])
+        @responses = responses
+        @response_index = 0
+        @calls = []
+      end
+
+      # ASYNC-READY: scheduler param is the async entry point
+      def stream(messages:, system: nil, tools: [], config: {}, scheduler: Scheduler::Sync.new, &chunk_handler)
+        @calls << { messages: messages, system: system, tools: tools, config: config }
+
+        response = next_response!
+
+        response[:chunks].each do |chunk|
+          chunk_handler.call(chunk)
+        end
+
+        response
+      end
+
+      def call_count
+        @calls.length
+      end
+
+      private
+
+      def next_response!
+        if @response_index >= @responses.length
+          raise "StubAdapter exhausted: #{@responses.length} responses configured, " \
+                "but call ##{@response_index + 1} was made."
+        end
+
+        response = @responses[@response_index]
+        @response_index += 1
+        response
+      end
+    end
+  end
+end

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