spurline-dashboard 0.3.0

data/lib/spurline/security/content.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Security
+    # The cardinal type of the Spurline framework. Every piece of content flowing
+    # through the system is a Content object carrying a trust level and source.
+    # Raw strings never enter the context pipeline.
+    #
+    # Content objects are frozen on creation and cannot be mutated.
+    class Content
+      TRUST_LEVELS = %i[system operator user external untrusted].freeze
+
+      TAINTED_LEVELS = %i[external untrusted].freeze
+
+      attr_reader :text, :trust, :source
+
+      def initialize(text:, trust:, source:)
+        validate_trust!(trust)
+
+        @text = text.dup.freeze
+        @trust = trust
+        @source = source.dup.freeze
+        freeze
+      end
+
+      # Raises TaintedContentError for tainted content. Use #render instead.
+      def to_s
+        if tainted?
+          raise Spurline::TaintedContentError,
+            "Cannot convert tainted content (trust: #{trust}, source: #{source}) to string. " \
+            "Use Content#render to get a safely fenced string."
+        end
+
+        text
+      end
+
+      # Returns the content as a string, applying XML data fencing for tainted content.
+      # This is the ONLY safe way to extract a string from tainted content.
+      def render
+        return text unless tainted?
+
+        <<~XML.strip
+          <external_data trust="#{trust}" source="#{source}">
+          #{text}
+          </external_data>
+        XML
+      end
+
+      def tainted?
+        TAINTED_LEVELS.include?(trust)
+      end
+
+      def ==(other)
+        other.is_a?(Content) &&
+          text == other.text &&
+          trust == other.trust &&
+          source == other.source
+      end
+
+      def inspect
+        "#<Spurline::Security::Content trust=#{trust} source=#{source.inspect} " \
+          "text=#{text[0..50].inspect}#{text.length > 50 ? "..." : ""}>"
+      end
+
+      private
+
+      def validate_trust!(trust)
+        return if TRUST_LEVELS.include?(trust)
+
+        raise Spurline::ConfigurationError,
+          "Invalid trust level: #{trust.inspect}. " \
+          "Must be one of: #{TRUST_LEVELS.map(&:inspect).join(", ")}."
+      end
+    end
+  end
+end

data/lib/spurline/security/context_pipeline.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Security
+    # The only path content takes to the LLM. Every LLM call assembles context
+    # through this pipeline. The stages run in fixed order and cannot be reordered.
+    #
+    # Pipeline stages:
+    #   1. Injection scanning — detect and block prompt injection attempts
+    #   2. PII filtering — redact/block/warn on personally identifiable information
+    #   3. Data fencing — render tainted content with XML fencing
+    #
+    # Input: Array of Content objects at various trust levels
+    # Output: Array of rendered strings, safe for inclusion in an LLM prompt
+    class ContextPipeline
+      def initialize(guardrails: {})
+        @scanner = InjectionScanner.new(
+          level: guardrails.fetch(:injection_filter, :strict)
+        )
+        @pii_filter = PIIFilter.new(
+          mode: guardrails.fetch(:pii_filter, :off)
+        )
+      end
+
+      # Processes an array of Content objects through the full security pipeline.
+      # Returns an array of safe, rendered strings ready for the LLM.
+      #
+      # Raises InjectionAttemptError if injection patterns are detected.
+      def process(contents)
+        contents.map do |content|
+          validate_content!(content)
+          scan!(content)
+          filtered = filter(content)
+          filtered.render
+        end
+      end
+
+      private
+
+      def validate_content!(content)
+        return if content.is_a?(Content)
+
+        raise Spurline::TaintedContentError,
+          "ContextPipeline received #{content.class.name} instead of " \
+          "Spurline::Security::Content. All content must enter through a Gate. " \
+          "Raw strings are never allowed in the pipeline."
+      end
+
+      def scan!(content)
+        @scanner.scan!(content)
+      end
+
+      def filter(content)
+        @pii_filter.filter(content)
+      end
+    end
+  end
+end

data/lib/spurline/security/gates/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Security
+    module Gates
+      # Abstract base class for security gates. Each gate wraps raw input
+      # into a Content object with the appropriate trust level and source.
+      #
+      # All external data enters the framework through exactly one of four gates.
+      # Nothing bypasses a gate.
+      class Base
+        class << self
+          # Wraps raw text into a Content object with the gate's trust level.
+          # Subclasses must implement #trust_level and #source_for.
+          def wrap(text, **metadata)
+            Content.new(
+              text: text,
+              trust: trust_level,
+              source: source_for(**metadata)
+            )
+          end
+
+          private
+
+          def trust_level
+            raise NotImplementedError, "#{name} must implement .trust_level"
+          end
+
+          def source_for(**_metadata)
+            raise NotImplementedError, "#{name} must implement .source_for"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/security/gates/operator_config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Security
+    module Gates
+      # Gate for developer-authored configuration. Trust level: :operator.
+      class OperatorConfig < Base
+        class << self
+          private
+
+          def trust_level
+            :operator
+          end
+
+          def source_for(key: "config", **)
+            "config:#{key}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/security/gates/system_prompt.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Security
+    module Gates
+      # Gate for framework and persona prompts. Trust level: :system.
+      # System prompts are trusted by definition and bypass the injection scanner.
+      class SystemPrompt < Base
+        class << self
+          private
+
+          def trust_level
+            :system
+          end
+
+          def source_for(persona: "default", **)
+            "persona:#{persona}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/security/gates/tool_result.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Security
+    module Gates
+      # Gate for tool execution results. Trust level: :external.
+      # Tool results are always tainted — they come from outside the trust boundary.
+      class ToolResult < Base
+        class << self
+          private
+
+          def trust_level
+            :external
+          end
+
+          def source_for(tool_name: "unknown", **)
+            "tool:#{tool_name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/security/gates/user_input.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Security
+    module Gates
+      # Gate for live user messages. Trust level: :user.
+      class UserInput < Base
+        class << self
+          private
+
+          def trust_level
+            :user
+          end
+
+          def source_for(user_id: "anonymous", **)
+            "user:#{user_id}"
+          end
+        end
+      end
+    end
+  end
+end

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/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 |
+|----|------|---|-------|------|
+| #3782 | 10:23 PM | 🔵 | Spurline session and state machine architecture analyzed for suspended sessions feature | ~700 |
+</claude-mem-context>

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