spurline-core 0.3.0

data/lib/spurline/lifecycle/runner.rb

@@ -0,0 +1,456 @@
+# frozen_string_literal: true
+
+require "time"
+require "securerandom"
+require_relative "suspension_boundary"
+
+module Spurline
+  module Lifecycle
+    # The LLM call loop. Orchestrates context assembly, streaming, tool execution,
+    # and stop condition checking. This is the core engine of the framework.
+    #
+    # Stop conditions:
+    #   - Text response from the LLM (normal completion)
+    #   - max_tool_calls exceeded
+    #   - max_turns exceeded (multi-loop safety valve)
+    class Runner
+      def initialize(
+        adapter:,
+        pipeline:,
+        tool_runner:,
+        memory:,
+        assembler:,
+        audit:,
+        guardrails:,
+        suspension_check: nil,
+        scope: nil,
+        idempotency_ledger: nil
+      )
+        @adapter = adapter
+        @pipeline = pipeline
+        @tool_runner = tool_runner
+        @memory = memory
+        @assembler = assembler
+        @audit = audit
+        @guardrails = guardrails
+        @suspension_check = suspension_check || Lifecycle::SuspensionCheck.none
+        @scope = scope
+        @idempotency_ledger = idempotency_ledger
+        @loop_count = 0
+        @messages_so_far = []
+        @last_tool_result = nil
+      end
+
+      # ASYNC-READY: the main call loop
+      def run(
+        input:,
+        session:,
+        persona:,
+        tools_schema:,
+        adapter_config:,
+        agent_context: nil,
+        resume_checkpoint: nil,
+        &chunk_handler
+      )
+        turn, input, parent_episode_id = initialize_turn_context(
+          session: session,
+          input: input,
+          resume_checkpoint: resume_checkpoint
+        )
+
+        loop do
+          @loop_count += 1
+          check_max_turns!
+
+          # 1. Assemble context
+          contents = @assembler.assemble(
+            input: input,
+            memory: @memory,
+            persona: persona,
+            session: session,
+            agent_context: agent_context
+          )
+
+          # 2. Process through security pipeline
+          processed = @pipeline.process(contents)
+
+          # Separate system prompt from messages while preserving role semantics.
+          system_prompt, messages = build_messages(contents, processed, input)
+
+          # On the first loop, seed @messages_so_far with the initial messages.
+          # On subsequent loops, the conversation history is already accumulated
+          # via assistant tool_use and tool_result entries appended below.
+          if @loop_count == 1
+            @messages_so_far = messages.map(&:dup)
+          end
+
+          check_suspension!(
+            boundary_type: :before_llm_call,
+            turn: turn,
+            context: {
+              loop_iteration: @loop_count,
+              turn_number: turn.number,
+            }
+          )
+
+          # 3. Stream LLM response
+          buffer = Streaming::Buffer.new
+          @audit.record(:llm_request,
+            turn: turn.number,
+            loop: @loop_count,
+            message_count: @messages_so_far.length,
+            has_tools: !tools_schema.empty?,
+            tool_count: tools_schema.length)
+
+          @adapter.stream(
+            messages: @messages_so_far,
+            system: system_prompt,
+            tools: tools_schema,
+            config: adapter_config
+          ) do |chunk|
+            buffer << chunk
+            chunk_handler&.call(chunk) if chunk.text?
+          end
+          @audit.record(:llm_response,
+            turn: turn.number,
+            loop: @loop_count,
+            stop_reason: buffer.stop_reason,
+            tool_call_count: buffer.tool_call_count,
+            text_length: buffer.full_text.length)
+
+          # 4. Parse response
+          if buffer.tool_call?
+            tool_calls = buffer.tool_calls
+
+            # Append assistant tool_use message to conversation history
+            tool_use_blocks = tool_calls.map do |tc|
+              tool_use_id = find_tool_use_id(buffer, tc[:name])
+              {
+                type: "tool_use",
+                id: tool_use_id || "toolu_#{SecureRandom.hex(12)}",
+                name: tc[:name],
+                input: tc[:arguments] || {},
+              }
+            end
+            @messages_so_far << { role: "assistant", content: tool_use_blocks }
+
+            tool_calls.each do |tool_call|
+              filtered_args = Audit::SecretFilter.filter(
+                tool_call[:arguments],
+                tool_name: tool_call[:name],
+                registry: @tool_runner.registry
+              )
+              decision_episode_id = record_episode(
+                session: session,
+                turn: turn,
+                type: :decision,
+                content: "Model requested tool call",
+                metadata: {
+                  decision: "invoke_tool",
+                  tool_name: tool_call[:name],
+                  arguments: filtered_args,
+                  loop: @loop_count,
+                },
+                parent_episode_id: parent_episode_id
+              )
+              tool_episode_id = record_episode(
+                session: session,
+                turn: turn,
+                type: :tool_call,
+                content: filtered_args,
+                metadata: {
+                  tool_name: tool_call[:name],
+                  loop: @loop_count,
+                },
+                parent_episode_id: decision_episode_id || parent_episode_id
+              )
+
+              # Check guardrails
+              if session.tool_call_count >= @guardrails[:max_tool_calls]
+                @audit.record(:max_tool_calls_reached,
+                  limit: @guardrails[:max_tool_calls])
+                raise Spurline::MaxToolCallsError,
+                  "Tool call limit reached (#{@guardrails[:max_tool_calls]}). " \
+                  "Increase max_tool_calls in the agent's guardrails block."
+              end
+
+              # Yield tool_start chunk
+              chunk_handler&.call(
+                Streaming::Chunk.new(
+                  type: :tool_start,
+                  turn: turn.number,
+                  session_id: session.id,
+                  metadata: { tool_name: tool_call[:name], arguments: filtered_args }
+                )
+              )
+
+              # 5. Execute tool
+              started = Time.now
+              result = @tool_runner.execute(
+                tool_call,
+                session: session,
+                scope: @scope,
+                idempotency_ledger: @idempotency_ledger
+              )
+              duration_ms = ((Time.now - started) * 1000).round
+
+              @audit.record(:tool_call,
+                tool: tool_call[:name],
+                arguments: tool_call[:arguments],
+                duration_ms: duration_ms,
+                turn: turn.number,
+                loop: @loop_count)
+
+              # Yield tool_end chunk
+              chunk_handler&.call(
+                Streaming::Chunk.new(
+                  type: :tool_end,
+                  turn: turn.number,
+                  session_id: session.id,
+                  metadata: { tool_name: tool_call[:name], duration_ms: duration_ms }
+                )
+              )
+
+              @audit.record(:tool_result,
+                tool: tool_call[:name],
+                turn: turn.number,
+                loop: @loop_count,
+                result_length: result.text.to_s.length,
+                trust: result.trust)
+              parent_episode_id = record_episode(
+                session: session,
+                turn: turn,
+                type: :external_data,
+                content: result,
+                metadata: {
+                  source: "tool:#{tool_call[:name]}",
+                  trust: result.trust,
+                  loop: @loop_count,
+                },
+                parent_episode_id: tool_episode_id || decision_episode_id || parent_episode_id
+              ) || parent_episode_id
+
+              # 6. Append tool_result to conversation history for the LLM
+              tool_use_id = find_tool_use_id(buffer, tool_call[:name])
+              result_text = result.respond_to?(:text) ? result.text : result.to_s
+              result_content = result_text.is_a?(String) ? result_text : JSON.generate(result_text)
+              @messages_so_far << {
+                role: "user",
+                content: [{
+                  type: "tool_result",
+                  tool_use_id: tool_use_id || "toolu_#{SecureRandom.hex(12)}",
+                  content: result_content,
+                }],
+              }
+
+              @last_tool_result = serialize_tool_result(result)
+              check_suspension!(
+                boundary_type: :after_tool_result,
+                turn: turn,
+                context: {
+                  loop_iteration: @loop_count,
+                  turn_number: turn.number,
+                  tool_name: tool_call[:name],
+                }
+              )
+              input = result
+            end
+
+            # Continue the loop
+            next
+          else
+            # Text response — the agent is done
+            output_text = buffer.full_text
+            output_content = Security::Gates::OperatorConfig.wrap(
+              output_text, key: "llm_response"
+            )
+            decision_episode_id = record_episode(
+              session: session,
+              turn: turn,
+              type: :decision,
+              content: "Model returned final response",
+              metadata: {
+                decision: "final_response",
+                stop_reason: buffer.stop_reason,
+                loop: @loop_count,
+              },
+              parent_episode_id: parent_episode_id
+            )
+            record_episode(
+              session: session,
+              turn: turn,
+              type: :assistant_response,
+              content: output_content,
+              metadata: {
+                source: output_content.source,
+                trust: output_content.trust,
+                loop: @loop_count,
+              },
+              parent_episode_id: decision_episode_id || parent_episode_id
+            )
+
+            turn.finish!(output: output_content)
+            @memory.add_turn(turn)
+
+            # Yield done chunk
+            chunk_handler&.call(
+              Streaming::Chunk.new(
+                type: :done,
+                turn: turn.number,
+                session_id: session.id,
+                metadata: { stop_reason: "end_turn" }
+              )
+            )
+
+            @audit.record(:turn_end, turn: turn.number,
+              duration_ms: turn.duration_ms,
+              tool_calls: turn.tool_call_count)
+            break
+          end
+        end
+      end
+
+      private
+
+      def initialize_turn_context(session:, input:, resume_checkpoint:)
+        if resume_checkpoint
+          @loop_count = checkpoint_value(resume_checkpoint, :loop_iteration).to_i
+          @last_tool_result = checkpoint_value(resume_checkpoint, :last_tool_result)
+          @messages_so_far = Array(checkpoint_value(resume_checkpoint, :messages_so_far)).map do |entry|
+            entry.is_a?(Hash) ? entry.dup : entry
+          end
+
+          turn = session.current_turn
+          if turn.nil? || turn.complete?
+            turn = session.start_turn(input: input)
+            @audit.record(:turn_start, turn: turn.number)
+          end
+
+          return [turn, input, nil]
+        end
+
+        @loop_count = 0
+        @last_tool_result = nil
+        @messages_so_far = []
+
+        turn = session.start_turn(input: input)
+        @audit.record(:turn_start, turn: turn.number)
+        parent_episode_id = record_episode(
+          session: session,
+          turn: turn,
+          type: :user_message,
+          content: input,
+          metadata: {
+            source: input.respond_to?(:source) ? input.source : "user:input",
+            trust: input.respond_to?(:trust) ? input.trust : :user,
+          }
+        )
+        [turn, input, parent_episode_id]
+      end
+
+      def check_suspension!(boundary_type:, turn:, context: {})
+        boundary = SuspensionBoundary.new(type: boundary_type, context: context)
+        decision = @suspension_check.call(boundary)
+        return if decision == :continue
+
+        raise SuspensionSignal.new(checkpoint: suspension_checkpoint(turn: turn, context: context))
+      end
+
+      def suspension_checkpoint(turn:, context:)
+        {
+          loop_iteration: @loop_count,
+          last_tool_result: @last_tool_result,
+          messages_so_far: @messages_so_far.dup,
+          turn_number: turn.number,
+          suspended_at: Time.now.utc.iso8601,
+          suspension_reason: context[:suspension_reason],
+        }
+      end
+
+      def checkpoint_value(checkpoint, key)
+        checkpoint[key] || checkpoint[key.to_s]
+      end
+
+      def find_tool_use_id(buffer, tool_name)
+        chunk = buffer.chunks.find do |c|
+          c.metadata[:tool_name] == tool_name && c.metadata[:tool_use_id]
+        end
+        chunk&.metadata&.dig(:tool_use_id)
+      end
+
+      def serialize_tool_result(result)
+        return nil if result.nil?
+        return result.text if result.respond_to?(:text)
+
+        result.to_s
+      end
+
+      def check_max_turns!
+        max = @guardrails[:max_turns] || 50
+        return if @loop_count <= max
+
+        raise Spurline::MaxToolCallsError,
+          "Loop iteration limit reached (#{max}). The agent has looped #{@loop_count} times " \
+          "without producing a final text response. Check tool behavior or increase max_turns."
+      end
+
+      def build_messages(contents, processed, input)
+        system_parts = []
+        messages = []
+
+        contents.zip(processed).each do |content, rendered|
+          next unless rendered
+
+          if content.trust == :system
+            system_parts << rendered
+            next
+          end
+
+          messages << {
+            role: role_for(content),
+            content: rendered,
+          }
+        end
+
+        # Ensure at least one user message
+        if messages.empty?
+          text = input.is_a?(Security::Content) ? input.render : input.to_s
+          messages << { role: "user", content: text }
+        end
+
+        [system_parts.join("\n\n"), messages]
+      end
+
+      def role_for(content)
+        return "assistant" if content.source == "config:llm_response"
+
+        "user"
+      end
+
+      def record_episode(session:, turn:, type:, content:, metadata:, parent_episode_id: nil)
+        return nil unless @memory.respond_to?(:record_episode)
+
+        episode = @memory.record_episode(
+          type: type,
+          content: content,
+          metadata: metadata,
+          turn_number: turn.number,
+          parent_episode_id: parent_episode_id
+        )
+        return nil unless episode
+
+        persist_episode_state!(session)
+        episode.id
+      end
+
+      def persist_episode_state!(session)
+        return unless @memory.respond_to?(:episodic)
+
+        episodic = @memory.episodic
+        return unless episodic
+
+        session.metadata[:episodes] = episodic.serialize
+      end
+    end
+  end
+end

data/lib/spurline/lifecycle/states.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Lifecycle
+    # State machine for agent lifecycle. Invalid transitions raise InvalidStateError.
+    #
+    # The :complete -> :running transition is intentional — it allows multi-turn
+    # conversations via #chat, where each turn goes through the full lifecycle.
+    module States
+      STATES = %i[
+        uninitialized
+        ready
+        running
+        waiting_for_tool
+        processing
+        suspended
+        finishing
+        complete
+        error
+      ].freeze
+
+      VALID_TRANSITIONS = {
+        uninitialized: [:ready],
+        ready: [:running],
+        running: [:waiting_for_tool, :finishing, :suspended, :error],
+        waiting_for_tool: [:processing, :suspended, :error],
+        processing: [:running, :finishing, :suspended, :error],
+        suspended: [:running],
+        finishing: [:complete, :error],
+        complete: [:running],
+        error: [],
+      }.freeze
+
+      def self.valid_transition?(from, to)
+        VALID_TRANSITIONS.fetch(from, []).include?(to)
+      end
+
+      def self.validate_transition!(from, to)
+        return if valid_transition?(from, to)
+
+        raise Spurline::InvalidStateError,
+          "Invalid state transition: #{from} -> #{to}. " \
+          "Valid transitions from #{from}: #{VALID_TRANSITIONS[from].inspect}."
+      end
+    end
+  end
+end

data/lib/spurline/lifecycle/suspension_boundary.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Lifecycle
+    # Immutable value object marking where suspension can happen.
+    # Types: :after_tool_result, :before_llm_call
+    class SuspensionBoundary
+      TYPES = %i[after_tool_result before_llm_call].freeze
+
+      attr_reader :type, :context
+
+      def initialize(type:, context: {})
+        normalized_type = type.to_sym
+        unless TYPES.include?(normalized_type)
+          raise ArgumentError,
+            "Invalid suspension boundary type #{type.inspect}. " \
+            "Expected one of #{TYPES.inspect}."
+        end
+
+        unless context.is_a?(Hash)
+          raise ArgumentError, "Suspension boundary context must be a Hash"
+        end
+
+        @type = normalized_type
+        @context = context.dup.freeze
+        freeze
+      end
+    end
+
+    # Internal flow control signal — NOT an error class.
+    # Raised by Runner when suspension_check returns :suspend.
+    # Caught by Agent to trigger session suspension.
+    class SuspensionSignal < StandardError
+      attr_reader :checkpoint
+
+      def initialize(checkpoint:)
+        @checkpoint = checkpoint
+        super("Agent suspended at boundary")
+      end
+    end
+
+    # Callable interface for suspension decisions.
+    # Receives a SuspensionBoundary, returns :continue or :suspend.
+    class SuspensionCheck
+      def initialize(&block)
+        @check = block || ->(_boundary) { :continue }
+      end
+
+      def call(boundary)
+        result = @check.call(boundary)
+        unless %i[continue suspend].include?(result)
+          raise ArgumentError,
+            "SuspensionCheck must return :continue or :suspend, got #{result.inspect}"
+        end
+
+        result
+      end
+
+      # Factory: always continue (default)
+      def self.none
+        new { :continue }
+      end
+
+      # Factory: suspend after N tool calls
+      def self.after_tool_calls(n)
+        unless n.is_a?(Integer) && n.positive?
+          raise ArgumentError, "n must be a positive Integer"
+        end
+
+        count = 0
+        new do |boundary|
+          if boundary.type == :after_tool_result
+            count += 1
+            count >= n ? :suspend : :continue
+          else
+            :continue
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/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 |
+|----|------|---|-------|------|
+| #3664 | 8:45 PM | 🔵 | Spurline Milestone 1 implementation status audit completed | ~598 |
+| #3631 | 6:00 PM | ⚖️ | Long-term memory architecture with pgvector and OpenAI embeddings | ~501 |
+</claude-mem-context>

data/lib/spurline/memory/context_assembler.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+require "date"
+
+module Spurline
+  module Memory
+    # Assembles context for the LLM from persona, memory, and user input.
+    # Returns an ordered array of Content objects — never raw strings.
+    #
+    # Assembly order:
+    #   1. System prompt (trust: :system)
+    #   2. Persona supplements (trust: :system, optional)
+    #   3. Recalled long-term memories (trust: :operator, optional)
+    #   4. Recent conversation history (trust: inherited from original)
+    #   5. Current user input (trust: :user)
+    class ContextAssembler
+      def assemble(input:, memory:, persona:, session: nil, agent_context: nil)
+        contents = []
+
+        # 1. System prompt (trust: :system)
+        contents << persona.render if persona
+
+        # 2. Persona injection supplements (trust: :system)
+        if persona
+          inject_persona_supplements!(
+            contents,
+            persona,
+            session: session,
+            agent_context: agent_context
+          )
+        end
+
+        # 3. Recalled long-term memories (trust: :operator)
+        if memory.respond_to?(:recall)
+          recalled = memory.recall(query: extract_query_text(input), limit: 5)
+          contents.concat(recalled) if recalled.any?
+        end
+
+        # 4. Recent conversation history (trust: inherited from original)
+        memory.recent_turns.each do |turn|
+          contents << turn.input if turn.input.is_a?(Security::Content)
+          contents << turn.output if turn.output.is_a?(Security::Content)
+        end
+
+        # 5. Current user input (trust: :user)
+        contents << input if input.is_a?(Security::Content)
+
+        contents.compact
+      end
+
+      # Estimates token count for assembled context. Rough approximation
+      # at ~4 characters per token. Used for trimming decisions.
+      def estimate_tokens(contents)
+        contents.sum { |c| (c.text.length / 4.0).ceil }
+      end
+
+      private
+
+      def inject_persona_supplements!(contents, persona, session:, agent_context:)
+        if persona.inject_date?
+          contents << Security::Gates::SystemPrompt.wrap(
+            "Current date: #{Date.today.iso8601}",
+            persona: "injection:date"
+          )
+        end
+
+        if persona.inject_user_context? && session&.user
+          contents << Security::Gates::SystemPrompt.wrap(
+            "Current user: #{session.user}",
+            persona: "injection:user_context"
+          )
+        end
+
+        if persona.inject_agent_context? && agent_context
+          contents << Security::Gates::SystemPrompt.wrap(
+            build_agent_context_text(agent_context),
+            persona: "injection:agent_context"
+          )
+        end
+      end
+
+      def build_agent_context_text(context)
+        parts = []
+        parts << "Agent: #{context[:class_name]}" if context[:class_name]
+        if context[:tool_names]&.any?
+          parts << "Available tools: #{context[:tool_names].join(', ')}"
+        end
+        parts.join("\n")
+      end
+
+      def extract_query_text(input)
+        case input
+        when Security::Content
+          input.text
+        else
+          input.to_s
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/embedder/CLAUDE.md

@@ -0,0 +1,11 @@
+<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 |
+|----|------|---|-------|------|
+| #3664 | 8:45 PM | 🔵 | Spurline Milestone 1 implementation status audit completed | ~598 |
+</claude-mem-context>