spurline-deploy 0.3.0

data/lib/spurline/security/injection_scanner.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Security
+    # Scans Content objects for prompt injection patterns.
+    # Configurable strictness: :strict, :moderate, :permissive.
+    #
+    # Only scans content at trust levels that could be injected (:user, :external, :untrusted).
+    # System and operator content is trusted by definition and bypasses scanning.
+    #
+    # Pattern tiers are additive: :strict includes all :moderate patterns,
+    # :moderate includes all :permissive (BASE) patterns.
+    class InjectionScanner
+      SKIP_TRUST_LEVELS = %i[system operator].freeze
+
+      # Patterns checked at all strictness levels — the most obvious injection attempts.
+      BASE_PATTERNS = [
+        /ignore\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions|prompts|context|rules)/i,
+        /you\s+are\s+now\s+(a|an|in)\s+/i,
+        /\bsystem\s*:\s*\n/i,
+        /\bforget\s+(all\s+|everything\s+)?(previous|prior|your)\s+(instructions|context|rules|training)/i,
+        /\bdisregard\s+(all\s+)?(previous|prior|above|your)\s+(instructions|prompts|rules)/i,
+        /\bnew\s+instructions\s*:/i,
+        /\bpretend\s+(you\s+are|to\s+be|that\s+you)/i,
+      ].freeze
+
+      # Additional patterns for :moderate and :strict — social engineering and role manipulation.
+      MODERATE_PATTERNS = [
+        /\bdo\s+not\s+follow\b/i,
+        /\boverride\s+(your|the)\s+(instructions|rules|guidelines|programming)\b/i,
+        /\bact\s+as\s+(if\s+you\s+are|though\s+you|a\b)/i,
+        /\bbehave\s+as\s+(if|though|a\b)/i,
+        /\bfrom\s+now\s+on\s*,?\s*(you|your|act|behave|respond|ignore)/i,
+        /\bjailbreak/i,
+        /\bdeveloper\s+mode\b/i,
+        /\bDAN\s+(mode|prompt)\b/i,
+        /\bdo\s+anything\s+now\b/i,
+        /\bunfiltered\s+(mode|response|output)\b/i,
+        /\bno\s+(restrictions|rules|limitations|filters|censorship)\b/i,
+        /\bbypass\s+(your|the|any|all)\s+(restrictions|rules|filters|safety|guidelines)/i,
+      ].freeze
+
+      # Additional patterns for :strict only — structural attacks and format manipulation.
+      STRICT_PATTERNS = [
+        /\brole\s*:\s*(system|assistant)\b/i,
+        /<\/?system>/i,
+        /\[INST\]/i,
+        /<<\s*SYS\s*>>/i,
+        /<\|im_start\|>/i,
+        /\bIMPORTANT\s*:\s*(new|override|ignore|forget|disregard|update)/i,
+        /\bATTENTION\s*:\s*(new|override|ignore|forget|disregard|update)/i,
+        /\b(BEGIN|END)\s+(SYSTEM|INSTRUCTION|PROMPT)\b/i,
+        /---+\s*\n\s*(system|instruction|new prompt|override)/i,
+        /\bbase64\s*[\s:]+[A-Za-z0-9+\/=]{20,}/i,
+        /\btranslate\s+(the\s+)?(following|this)\s+(from|to)\s+.*\s+(and|then)\s+(ignore|forget|override)/i,
+        /\brepeat\s+(the\s+)?(system\s+prompt|instructions|your\s+rules)/i,
+        /\b(reveal|show|display|output|print)\s+(your|the)\s+(system\s+prompt|instructions|rules)/i,
+      ].freeze
+
+      LEVELS = %i[strict moderate permissive].freeze
+
+      attr_reader :level
+
+      def initialize(level: :strict)
+        validate_level!(level)
+        @level = level
+      end
+
+      # Scans a Content object for injection patterns.
+      # Returns nil if clean, raises InjectionAttemptError if detected.
+      def scan!(content)
+        return if SKIP_TRUST_LEVELS.include?(content.trust)
+
+        text = content.text
+        patterns_for_level.each do |pattern|
+          next unless text.match?(pattern)
+
+          raise Spurline::InjectionAttemptError,
+            "Injection pattern detected in content (trust: #{content.trust}, " \
+            "source: #{content.source}). Pattern: #{pattern.source[0..40]}. " \
+            "Review the content or adjust injection_filter level."
+        end
+
+        nil
+      end
+
+      private
+
+      def patterns_for_level
+        case level
+        when :strict
+          BASE_PATTERNS + MODERATE_PATTERNS + STRICT_PATTERNS
+        when :moderate
+          BASE_PATTERNS + MODERATE_PATTERNS
+        when :permissive
+          BASE_PATTERNS
+        end
+      end
+
+      def validate_level!(level)
+        return if LEVELS.include?(level)
+
+        raise Spurline::ConfigurationError,
+          "Invalid injection filter level: #{level.inspect}. " \
+          "Must be one of: #{LEVELS.map(&:inspect).join(", ")}."
+      end
+    end
+  end
+end

data/lib/spurline/security/pii_filter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Security
+    # Filters personally identifiable information from Content objects.
+    # Modes:
+    #   :redact  — replaces detected PII with [REDACTED_<type>] placeholders
+    #   :block   — raises PIIDetectedError if PII is found
+    #   :warn    — returns content unchanged but records detections for audit
+    #   :off     — no scanning, returns content unchanged
+    #
+    # Only scans content at trust levels where PII matters (:user, :external, :untrusted).
+    # System and operator content is trusted by definition and bypasses PII filtering.
+    class PIIFilter
+      MODES = %i[redact block warn off].freeze
+
+      SKIP_TRUST_LEVELS = %i[system operator].freeze
+
+      # Pattern definitions: [label, regex, replacement_tag]
+      # Ordered from most specific to least specific to prevent partial matches.
+      PII_PATTERNS = [
+        [:ssn, /\b\d{3}-\d{2}-\d{4}\b/, "[REDACTED_SSN]"],
+        [:credit_card, /\b(?:\d{4}[\s-]?){3}\d{4}\b/, "[REDACTED_CREDIT_CARD]"],
+        [:phone, /\b(?:\+?1[\s.-]?)?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}\b/, "[REDACTED_PHONE]"],
+        [:email, /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/, "[REDACTED_EMAIL]"],
+        [:ip_address, /\b(?:\d{1,3}\.){3}\d{1,3}\b/, "[REDACTED_IP]"],
+      ].freeze
+
+      attr_reader :mode
+
+      def initialize(mode: :off)
+        validate_mode!(mode)
+        @mode = mode
+      end
+
+      # Filters a Content object for PII.
+      # Returns the original content if no PII is detected or mode is :off.
+      # Returns a new Content object with redacted text in :redact mode.
+      # Raises PIIDetectedError in :block mode.
+      # Returns the original content with detections array in :warn mode.
+      def filter(content)
+        return content if mode == :off
+        return content if SKIP_TRUST_LEVELS.include?(content.trust)
+
+        detections = detect(content.text)
+        return content if detections.empty?
+
+        case mode
+        when :redact
+          redact(content, detections)
+        when :block
+          block!(content, detections)
+        when :warn
+          # In :warn mode, content passes through unchanged.
+          # The caller (ContextPipeline) can check detections via the return.
+          # For now, we simply return the content — audit logging is deferred.
+          content
+        end
+      end
+
+      # Scans text for PII patterns. Returns array of {type:, match:, pattern:} hashes.
+      def detect(text)
+        detections = []
+        PII_PATTERNS.each do |label, pattern, _|
+          text.scan(pattern) do |match|
+            detected = match.is_a?(Array) ? match.first : $~.to_s
+            detections << { type: label, match: detected, pattern: pattern }
+          end
+        end
+        detections
+      end
+
+      private
+
+      def redact(content, detections)
+        redacted_text = content.text.dup
+        PII_PATTERNS.each do |_, pattern, replacement|
+          redacted_text.gsub!(pattern, replacement)
+        end
+
+        Content.new(
+          text: redacted_text,
+          trust: content.trust,
+          source: content.source
+        )
+      end
+
+      def block!(content, detections)
+        types = detections.map { |d| d[:type] }.uniq.join(", ")
+        raise Spurline::PIIDetectedError,
+          "PII detected in content (trust: #{content.trust}, source: #{content.source}). " \
+          "Types found: #{types}. Set pii_filter to :redact or :off to allow this content."
+      end
+
+      def validate_mode!(mode)
+        return if MODES.include?(mode)
+
+        raise Spurline::ConfigurationError,
+          "Invalid PII filter mode: #{mode.inspect}. " \
+          "Must be one of: #{MODES.map(&:inspect).join(", ")}."
+      end
+    end
+  end
+end

data/lib/spurline/session/resumption.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Session
+    # Handles restoring a resumed session's turn history into short-term memory.
+    # When a session is resumed by ID, completed turns are replayed into the
+    # memory manager so the agent has context from the previous conversation.
+    class Resumption
+      attr_reader :restored_count
+
+      def initialize(session:, memory:)
+        @session = session
+        @memory = memory
+        @restored_count = 0
+      end
+
+      # Restores the session's completed turn history into the memory manager.
+      # Incomplete turns are skipped — they represent interrupted work.
+      def restore!
+        @session.turns.each do |turn|
+          next unless turn.complete?
+
+          @memory.add_turn(turn)
+          @restored_count += 1
+        end
+
+        @restored_count
+      end
+
+      # Whether this session has prior turns to restore.
+      def resumable?
+        @session.turns.any?(&:complete?)
+      end
+    end
+  end
+end

data/lib/spurline/session/serializer.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Spurline
+  module Session
+    # JSON serializer/deserializer for persisted sessions.
+    # Includes a format_version field for forward-compatible migrations.
+    class Serializer
+      FORMAT_VERSION = 1
+      CONTENT_TYPE = "Spurline::Security::Content"
+      TIME_TYPE = "Time"
+      SYMBOL_TYPE = "Symbol"
+
+      def to_json(session)
+        JSON.generate(
+          format_version: FORMAT_VERSION,
+          session: serialize_session(session)
+        )
+      end
+
+      def from_json(json, store:)
+        payload = JSON.parse(json)
+        unless payload.is_a?(Hash)
+          raise Spurline::SessionDeserializationError, "Session payload must be a JSON object."
+        end
+
+        version = payload.fetch("format_version")
+        unless version == FORMAT_VERSION
+          raise Spurline::SessionDeserializationError,
+            "Unsupported session format version: #{version.inspect}."
+        end
+
+        session_data = deserialize_session(payload.fetch("session"))
+        Session.restore(session_data, store: store)
+      rescue Spurline::SessionDeserializationError
+        raise
+      rescue JSON::ParserError, KeyError, TypeError, NoMethodError, ArgumentError, Spurline::ConfigurationError => e
+        raise Spurline::SessionDeserializationError, "Failed to deserialize session payload: #{e.message}"
+      end
+
+      private
+
+      def serialize_session(session)
+        {
+          id: session.id,
+          agent_class: session.agent_class,
+          user: session.user,
+          state: session.state.to_s,
+          started_at: serialize_value(session.started_at),
+          finished_at: serialize_value(session.finished_at),
+          metadata: serialize_value(session.metadata),
+          turns: session.turns.map { |turn| serialize_turn(turn) },
+        }
+      end
+
+      def serialize_turn(turn)
+        {
+          input: serialize_value(turn.input),
+          output: serialize_value(turn.output),
+          tool_calls: serialize_value(turn.tool_calls),
+          number: turn.number,
+          started_at: serialize_value(turn.started_at),
+          finished_at: serialize_value(turn.finished_at),
+          metadata: serialize_value(turn.metadata),
+        }
+      end
+
+      def serialize_value(value)
+        case value
+        when Spurline::Security::Content
+          {
+            __type: CONTENT_TYPE,
+            text: value.text,
+            trust: value.trust.to_s,
+            source: value.source,
+          }
+        when Time
+          {
+            __type: TIME_TYPE,
+            iso8601: value.utc.iso8601(6),
+          }
+        when Symbol
+          {
+            __type: SYMBOL_TYPE,
+            value: value.to_s,
+          }
+        when Array
+          value.map { |item| serialize_value(item) }
+        when Hash
+          value.each_with_object({}) do |(key, item), hash|
+            hash[key.to_s] = serialize_value(item)
+          end
+        else
+          value
+        end
+      end
+
+      def deserialize_session(data)
+        hash = deserialize_hash(data)
+        {
+          id: hash.fetch(:id),
+          agent_class: hash[:agent_class],
+          user: hash[:user],
+          turns: Array(hash[:turns]).map { |turn_data| Turn.restore(deserialize_turn(turn_data)) },
+          state: hash.fetch(:state).to_sym,
+          started_at: hash.fetch(:started_at),
+          finished_at: hash[:finished_at],
+          metadata: hash[:metadata] || {},
+        }
+      end
+
+      def deserialize_turn(data)
+        hash = deserialize_hash(data)
+        {
+          input: hash[:input],
+          output: hash[:output],
+          tool_calls: hash[:tool_calls] || [],
+          number: hash.fetch(:number),
+          started_at: hash.fetch(:started_at),
+          finished_at: hash[:finished_at],
+          metadata: hash[:metadata] || {},
+        }
+      end
+
+      def deserialize_hash(value)
+        hash = deserialize_value(value)
+        unless hash.is_a?(Hash)
+          raise TypeError, "Expected Hash value, got #{hash.class}."
+        end
+
+        hash
+      end
+
+      def deserialize_value(value)
+        case value
+        when Array
+          value.map { |item| deserialize_value(item) }
+        when Hash
+          deserialize_hash_value(value)
+        else
+          value
+        end
+      end
+
+      def deserialize_hash_value(value)
+        type = value["__type"]
+
+        case type
+        when CONTENT_TYPE
+          Spurline::Security::Content.new(
+            text: value.fetch("text"),
+            trust: value.fetch("trust").to_sym,
+            source: value.fetch("source")
+          )
+        when TIME_TYPE
+          Time.iso8601(value.fetch("iso8601"))
+        when SYMBOL_TYPE
+          value.fetch("value").to_sym
+        else
+          value.each_with_object({}) do |(key, item), hash|
+            hash[key.to_sym] = deserialize_value(item)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/session/session.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Spurline
+  module Session
+    # The running record of an agent conversation. Framework-owned (ADR-004).
+    # Sessions are created via .load_or_create — never call .new directly in agent code.
+    #
+    # State transitions are enforced via Lifecycle::States.
+    class Session
+      attr_reader :id, :agent_class, :user, :turns, :state,
+                  :started_at, :finished_at, :metadata
+
+      def initialize(id:, store:, agent_class: nil, user: nil)
+        @id = id
+        @store = store
+        @agent_class = agent_class
+        @user = user
+        @turns = []
+        @state = :ready
+        @started_at = Time.now
+        @finished_at = nil
+        @metadata = {}
+      end
+
+      # The only way to get a session. Loads an existing session by ID,
+      # or creates a new one if it doesn't exist.
+      def self.load_or_create(id: nil, store:, **opts)
+        id ||= SecureRandom.uuid
+
+        if store.exists?(id)
+          store.load(id)
+        else
+          session = new(id: id, store: store, **opts)
+          store.save(session)
+          session
+        end
+      end
+
+      # Rebuilds a session from persisted attributes without running initialize.
+      def self.restore(data, store:)
+        session = allocate
+        session.instance_variable_set(:@id, data[:id])
+        session.instance_variable_set(:@store, store)
+        session.instance_variable_set(:@agent_class, data[:agent_class])
+        session.instance_variable_set(:@user, data[:user])
+        session.instance_variable_set(:@turns, data[:turns])
+        session.instance_variable_set(:@state, data[:state])
+        session.instance_variable_set(:@started_at, data[:started_at])
+        session.instance_variable_set(:@finished_at, data[:finished_at])
+        session.instance_variable_set(:@metadata, data[:metadata] || {})
+        session
+      end
+
+      def start_turn(input:)
+        turn = Turn.new(input: input, number: turns.length + 1)
+        @turns << turn
+        @metadata[:last_turn_started_at] = turn.started_at
+        turn
+      end
+
+      def current_turn
+        @turns.last
+      end
+
+      def finish_turn!(output:)
+        current_turn&.finish!(output: output)
+        save!
+      end
+
+      def tool_calls
+        turns.flat_map(&:tool_calls)
+      end
+
+      def tool_call_count
+        tool_calls.length
+      end
+
+      def turn_count
+        turns.length
+      end
+
+      # Enforces valid state transitions via Lifecycle::States.
+      def transition_to!(new_state)
+        Lifecycle::States.validate_transition!(@state, new_state)
+        @state = new_state
+      end
+
+      def complete!
+        @state = :complete
+        @finished_at = Time.now
+        @metadata[:total_turns] = turn_count
+        @metadata[:total_tool_calls] = tool_call_count
+        @metadata[:total_duration_ms] = total_duration_ms
+        save!
+      end
+
+      def error!(error = nil)
+        @state = :error
+        @finished_at = Time.now
+        @metadata[:last_error] = error&.message
+        @metadata[:last_error_class] = error&.class&.name
+        save!
+      end
+
+      # Suspends the session and persists a checkpoint for later resumption.
+      def suspend!(checkpoint:)
+        Suspension.suspend!(self, checkpoint: checkpoint)
+      end
+
+      # Resumes a suspended session and clears the persisted checkpoint.
+      def resume!
+        Suspension.resume!(self)
+      end
+
+      # Whether the session is currently suspended.
+      def suspended?
+        Suspension.suspended?(self)
+      end
+
+      # Duration in seconds (float).
+      def duration
+        return nil unless finished_at
+
+        finished_at - started_at
+      end
+
+      # Duration in milliseconds (integer).
+      def total_duration_ms
+        return nil unless finished_at
+
+        ((finished_at - started_at) * 1000).round
+      end
+
+      # Compact summary for logging and debugging.
+      def summary
+        {
+          id: id,
+          state: state,
+          turns: turn_count,
+          tool_calls: tool_call_count,
+          duration_ms: total_duration_ms,
+        }
+      end
+
+      private
+
+      def save!
+        @store.save(self)
+      end
+    end
+  end
+end

data/lib/spurline/session/store/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Session
+    module Store
+      # Abstract interface for session storage adapters (ADR-004).
+      # The framework owns session persistence — developers do not manage it.
+      class Base
+        def save(session)
+          raise NotImplementedError, "#{self.class.name} must implement #save"
+        end
+
+        def load(id)
+          raise NotImplementedError, "#{self.class.name} must implement #load"
+        end
+
+        def delete(id)
+          raise NotImplementedError, "#{self.class.name} must implement #delete"
+        end
+
+        def exists?(id)
+          raise NotImplementedError, "#{self.class.name} must implement #exists?"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/session/store/memory.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Session
+    module Store
+      # In-memory session store. Suitable for development and testing.
+      # Data does not persist across process restarts.
+      # Thread-safe via Mutex for concurrent access.
+      class Memory < Base
+        def initialize
+          @store = {}
+          @mutex = Mutex.new
+        end
+
+        def save(session)
+          @mutex.synchronize { @store[session.id] = session }
+        end
+
+        def load(id)
+          @mutex.synchronize { @store[id] }
+        end
+
+        def delete(id)
+          @mutex.synchronize { @store.delete(id) }
+        end
+
+        def exists?(id)
+          @mutex.synchronize { @store.key?(id) }
+        end
+
+        def size
+          @mutex.synchronize { @store.size }
+        end
+
+        def clear!
+          @mutex.synchronize { @store.clear }
+        end
+
+        def ids
+          @mutex.synchronize { @store.keys.dup }
+        end
+      end
+    end
+  end
+end