spurline-deploy 0.3.0

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/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/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    module Embedder
+      class Base
+        def embed(_text)
+          raise NotImplementedError, "#{self.class.name} must implement #embed"
+        end
+
+        def dimensions
+          raise NotImplementedError, "#{self.class.name} must implement #dimensions"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/embedder/open_ai.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    module Embedder
+      class OpenAI < Base
+        DEFAULT_MODEL = "text-embedding-3-small"
+        DIMENSIONS = 1536
+
+        def initialize(api_key: nil, model: nil)
+          @api_key = resolve_api_key(api_key)
+          @model = model || DEFAULT_MODEL
+        end
+
+        def embed(text)
+          # ASYNC-READY: Embedding requests are blocking in v1 and run at this seam.
+          response = build_client.embeddings(parameters: { model: @model, input: text.to_s })
+          embedding = response.dig("data", 0, "embedding")
+
+          if embedding.is_a?(Array) && embedding.all? { |value| value.is_a?(Numeric) }
+            embedding
+          else
+            raise Spurline::EmbedderError,
+              "OpenAI embedding response did not include a valid embedding vector"
+          end
+        rescue Spurline::EmbedderError
+          raise
+        rescue StandardError => e
+          raise Spurline::EmbedderError, "OpenAI embedding failed: #{e.message}"
+        end
+
+        def dimensions
+          DIMENSIONS
+        end
+
+        private
+
+        def resolve_api_key(explicit_key)
+          candidates = [
+            explicit_key,
+            ENV.fetch("OPENAI_API_KEY", nil),
+            Spurline.credentials["openai_api_key"],
+          ]
+          key = candidates.find { |value| present_string?(value) }
+          return key if key
+
+          raise Spurline::ConfigurationError,
+            "Missing OpenAI API key for embedding model :openai. " \
+            "Set OPENAI_API_KEY, add openai_api_key to Spurline.credentials, " \
+            "or pass api_key:."
+        end
+
+        def present_string?(value)
+          return false if value.nil?
+          return !value.strip.empty? if value.respond_to?(:strip)
+
+          true
+        end
+
+        def build_client
+          require "openai"
+          ::OpenAI::Client.new(access_token: @api_key)
+        rescue LoadError
+          raise Spurline::EmbedderError,
+            "The 'openai' gem is required for embedding_model :openai"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/episode.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Spurline
+  module Memory
+    # Immutable value object representing one structured event in an agent session.
+    class Episode
+      attr_reader :id, :type, :content, :metadata, :timestamp, :turn_number, :parent_episode_id
+
+      def initialize(
+        type:,
+        content:,
+        metadata: {},
+        timestamp: Time.now,
+        turn_number: nil,
+        parent_episode_id: nil,
+        id: SecureRandom.uuid
+      )
+        @id = id.to_s
+        @type = type.to_sym
+        @content = content
+        @metadata = (metadata || {}).dup.freeze
+        @timestamp = timestamp
+        @turn_number = turn_number
+        @parent_episode_id = parent_episode_id
+        freeze
+      end
+
+      def to_h
+        {
+          id: id,
+          type: type,
+          content: content,
+          metadata: metadata,
+          timestamp: timestamp,
+          turn_number: turn_number,
+          parent_episode_id: parent_episode_id,
+        }
+      end
+
+      def self.from_h(data)
+        hash = data.transform_keys(&:to_sym)
+        new(
+          id: hash[:id],
+          type: hash.fetch(:type),
+          content: hash[:content],
+          metadata: hash[:metadata] || {},
+          timestamp: hash[:timestamp] || Time.now,
+          turn_number: hash[:turn_number],
+          parent_episode_id: hash[:parent_episode_id]
+        )
+      end
+    end
+  end
+end

data/lib/spurline/memory/episodic_store.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    # Structured per-session trace for replay and explainability.
+    class EpisodicStore
+      attr_reader :enabled
+
+      def initialize(enabled: true, episodes: [])
+        @enabled = enabled
+        @episodes = Array(episodes).map { |episode| coerce_episode(episode) }
+      end
+
+      def record(type:, content:, metadata: {}, turn_number: nil, parent_episode_id: nil, timestamp: Time.now)
+        return nil unless enabled
+
+        episode = Episode.new(
+          type: type,
+          content: content,
+          metadata: metadata,
+          timestamp: timestamp,
+          turn_number: turn_number,
+          parent_episode_id: parent_episode_id
+        )
+        @episodes << episode
+        episode
+      end
+
+      def all
+        @episodes.dup
+      end
+
+      def count
+        @episodes.length
+      end
+
+      def empty?
+        @episodes.empty?
+      end
+
+      def clear!
+        @episodes.clear
+      end
+
+      def for_turn(turn_number)
+        @episodes.select { |episode| episode.turn_number == turn_number }
+      end
+
+      def tool_calls
+        by_type(:tool_call)
+      end
+
+      def decisions
+        by_type(:decision)
+      end
+
+      def external_data
+        by_type(:external_data)
+      end
+
+      def user_messages
+        by_type(:user_message)
+      end
+
+      def assistant_responses
+        by_type(:assistant_response)
+      end
+
+      def find(id)
+        @episodes.find { |episode| episode.id == id }
+      end
+
+      def serialize
+        @episodes.map(&:to_h)
+      end
+
+      def restore(serialized_episodes)
+        @episodes = Array(serialized_episodes).map { |episode| coerce_episode(episode) }
+        self
+      end
+
+      def explain
+        return "No episodes recorded." if @episodes.empty?
+
+        @episodes.sort_by(&:timestamp).map do |episode|
+          turn_label = episode.turn_number ? "Turn #{episode.turn_number}" : "Turn ?"
+          "#{turn_label} | #{episode_label(episode)}#{episode_parent_label(episode)}"
+        end.join("\n")
+      end
+
+      private
+
+      def by_type(type)
+        target = type.to_sym
+        @episodes.select { |episode| episode.type == target }
+      end
+
+      def coerce_episode(episode)
+        return episode if episode.is_a?(Episode)
+
+        Episode.from_h(episode)
+      end
+
+      def episode_label(episode)
+        case episode.type
+        when :user_message
+          "User message: #{summarize(episode.content)}"
+        when :decision
+          decision = episode.metadata[:decision] || episode.metadata["decision"] || "decision"
+          "Decision (#{decision}): #{summarize(episode.content)}"
+        when :tool_call
+          tool_name = episode.metadata[:tool_name] || episode.metadata["tool_name"] || "unknown_tool"
+          "Tool call #{tool_name}: #{summarize(episode.content)}"
+        when :external_data
+          source = episode.metadata[:source] || episode.metadata["source"] || "external"
+          "External data (#{source}): #{summarize(episode.content)}"
+        when :assistant_response
+          "Assistant response: #{summarize(episode.content)}"
+        else
+          "#{episode.type}: #{summarize(episode.content)}"
+        end
+      end
+
+      def episode_parent_label(episode)
+        return "" unless episode.parent_episode_id
+
+        " [after #{episode.parent_episode_id}]"
+      end
+
+      def summarize(content)
+        text = case content
+               when Spurline::Security::Content
+                 content.text
+               when String
+                 content
+               else
+                 content.inspect
+               end
+
+        cleaned = text.to_s.gsub(/\s+/, " ").strip
+        return cleaned if cleaned.length <= 120
+
+        "#{cleaned[0, 117]}..."
+      end
+    end
+  end
+end

data/lib/spurline/memory/long_term/base.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    module LongTerm
+      class Base
+        def store(content:, metadata: {})
+          raise NotImplementedError, "#{self.class.name} must implement #store"
+        end
+
+        # Returns an array of Security::Content objects at :operator trust.
+        def retrieve(query:, limit: 5)
+          raise NotImplementedError, "#{self.class.name} must implement #retrieve"
+        end
+
+        def clear!
+          raise NotImplementedError, "#{self.class.name} must implement #clear!"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/long_term/postgres.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Spurline
+  module Memory
+    module LongTerm
+      class Postgres < Base
+        TABLE_NAME = "spurline_memories"
+
+        def initialize(connection_string:, embedder:)
+          @connection_string = connection_string
+          @embedder = embedder
+          @connection = nil
+        end
+
+        def store(content:, metadata: {})
+          embedding = @embedder.embed(content)
+          session_id = metadata[:session_id] || metadata["session_id"]
+          sql = <<~SQL
+            INSERT INTO #{TABLE_NAME} (session_id, content, embedding, metadata)
+            VALUES ($1, $2, $3::vector, $4::jsonb)
+          SQL
+          params = [
+            session_id,
+            content,
+            vector_literal(embedding),
+            JSON.generate(metadata),
+          ]
+
+          # ASYNC-READY: Database writes are synchronous in v1 at this boundary.
+          connection.exec_params(sql, params)
+        rescue StandardError => e
+          raise Spurline::LongTermMemoryError, "Failed storing long-term memory: #{e.message}"
+        end
+
+        def retrieve(query:, limit: 5)
+          query_embedding = @embedder.embed(query)
+          sql = <<~SQL
+            SELECT content, metadata
+            FROM #{TABLE_NAME}
+            ORDER BY embedding <-> $1::vector
+            LIMIT $2
+          SQL
+          params = [vector_literal(query_embedding), limit]
+          # ASYNC-READY: Database reads are synchronous in v1 at this boundary.
+          result = connection.exec_params(sql, params)
+
+          result.map do |row|
+            Security::Content.new(
+              text: row["content"],
+              trust: :operator,
+              source: "memory:long_term"
+            )
+          end
+        rescue StandardError => e
+          raise Spurline::LongTermMemoryError, "Failed retrieving long-term memory: #{e.message}"
+        end
+
+        def clear!
+          connection.exec("DELETE FROM #{TABLE_NAME}")
+        rescue StandardError => e
+          raise Spurline::LongTermMemoryError, "Failed clearing long-term memory: #{e.message}"
+        end
+
+        def create_table!
+          dim = @embedder.dimensions
+
+          connection.exec("CREATE EXTENSION IF NOT EXISTS vector")
+          connection.exec(<<~SQL)
+            CREATE TABLE IF NOT EXISTS #{TABLE_NAME} (
+              id BIGSERIAL PRIMARY KEY,
+              session_id TEXT,
+              content TEXT NOT NULL,
+              embedding vector(#{dim}) NOT NULL,
+              metadata JSONB DEFAULT '{}',
+              created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+          SQL
+          connection.exec(<<~SQL)
+            CREATE INDEX IF NOT EXISTS idx_#{TABLE_NAME}_session_id
+            ON #{TABLE_NAME} (session_id)
+          SQL
+        rescue StandardError => e
+          raise Spurline::LongTermMemoryError, "Failed creating long-term memory schema: #{e.message}"
+        end
+
+        private
+
+        def vector_literal(embedding)
+          "[#{embedding.join(",")}]"
+        end
+
+        def connection
+          @connection ||= begin
+            require "pg"
+            PG.connect(@connection_string)
+          rescue LoadError
+            raise Spurline::LongTermMemoryError,
+              "The 'pg' gem is required for long-term memory adapter :postgres"
+          end
+        end
+      end
+    end
+  end
+end