spurline-deploy 0.3.0

data/lib/spurline/orchestration/task_envelope.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Spurline
+  module Orchestration
+    # Immutable work unit for worker execution.
+    class TaskEnvelope
+      CURRENT_VERSION = "1.0"
+
+      attr_reader :task_id, :version, :instruction, :input_files,
+                  :constraints, :acceptance_criteria, :output_spec,
+                  :scoped_context, :parent_session_id,
+                  :max_turns, :max_tool_calls, :metadata
+
+      # @param instruction [String] Natural language task description (required)
+      # @param acceptance_criteria [Array<String>] What the output must contain (required)
+      # @param task_id [String] UUID (auto-generated)
+      # @param version [String] Schema version
+      # @param input_files [Array<Hash>] Files the worker needs { path:, content: }
+      # @param constraints [Hash] Behavioral limits { no_modify: [...], read_only: true, ... }
+      # @param output_spec [Hash] Expected output format { type: :patch|:file|:answer, ... }
+      # @param scoped_context [Object,nil] Optional execution scope (M2.3)
+      # @param parent_session_id [String,nil] For audit correlation
+      # @param max_turns [Integer] Safety limit (default 10)
+      # @param max_tool_calls [Integer] Safety limit (default 20)
+      # @param metadata [Hash] Arbitrary extra data
+      def initialize(
+        instruction:,
+        acceptance_criteria:,
+        task_id: SecureRandom.uuid,
+        version: CURRENT_VERSION,
+        input_files: [],
+        constraints: {},
+        output_spec: {},
+        scoped_context: nil,
+        parent_session_id: nil,
+        max_turns: 10,
+        max_tool_calls: 20,
+        metadata: {}
+      )
+        validate_instruction!(instruction)
+        validate_acceptance_criteria!(acceptance_criteria)
+        validate_limit!(max_turns, name: "max_turns")
+        validate_limit!(max_tool_calls, name: "max_tool_calls")
+
+        @task_id = task_id.to_s
+        @version = version.to_s
+        @instruction = instruction.to_s
+        @input_files = deep_copy(input_files || [])
+        @constraints = deep_copy(constraints || {})
+        @acceptance_criteria = acceptance_criteria.map(&:to_s)
+        @output_spec = deep_copy(output_spec || {})
+        @scoped_context = normalize_scoped_context(scoped_context)
+        @parent_session_id = parent_session_id&.to_s
+        @max_turns = max_turns
+        @max_tool_calls = max_tool_calls
+        @metadata = deep_copy(metadata || {})
+
+        deep_freeze(@input_files)
+        deep_freeze(@constraints)
+        deep_freeze(@acceptance_criteria)
+        deep_freeze(@output_spec)
+        deep_freeze(@metadata)
+        if @scoped_context.is_a?(Hash) || @scoped_context.is_a?(Array)
+          deep_freeze(@scoped_context)
+        elsif @scoped_context.respond_to?(:freeze)
+          @scoped_context.freeze
+        end
+        freeze
+      end
+
+      def to_h
+        {
+          task_id: task_id,
+          version: version,
+          instruction: instruction,
+          input_files: deep_copy(input_files),
+          constraints: deep_copy(constraints),
+          acceptance_criteria: deep_copy(acceptance_criteria),
+          output_spec: deep_copy(output_spec),
+          scoped_context: serialize_scoped_context(scoped_context),
+          parent_session_id: parent_session_id,
+          max_turns: max_turns,
+          max_tool_calls: max_tool_calls,
+          metadata: deep_copy(metadata),
+        }
+      end
+
+      def self.from_h(data)
+        hash = deep_symbolize(data || {})
+        new(
+          task_id: hash[:task_id] || SecureRandom.uuid,
+          version: hash[:version] || CURRENT_VERSION,
+          instruction: hash.fetch(:instruction),
+          input_files: hash[:input_files] || [],
+          constraints: hash[:constraints] || {},
+          acceptance_criteria: hash.fetch(:acceptance_criteria),
+          output_spec: hash[:output_spec] || {},
+          scoped_context: hash[:scoped_context],
+          parent_session_id: hash[:parent_session_id],
+          max_turns: hash[:max_turns] || 10,
+          max_tool_calls: hash[:max_tool_calls] || 20,
+          metadata: hash[:metadata] || {}
+        )
+      end
+
+      private
+
+      def validate_instruction!(value)
+        return if value.to_s.strip != ""
+
+        raise Spurline::TaskEnvelopeError, "instruction is required"
+      end
+
+      def validate_acceptance_criteria!(value)
+        unless value.is_a?(Array) && !value.empty?
+          raise Spurline::TaskEnvelopeError, "acceptance_criteria must be a non-empty array"
+        end
+
+        if value.any? { |criterion| criterion.to_s.strip.empty? }
+          raise Spurline::TaskEnvelopeError, "acceptance_criteria entries must be non-empty"
+        end
+      end
+
+      def validate_limit!(value, name:)
+        unless value.is_a?(Integer) && value.positive?
+          raise Spurline::TaskEnvelopeError, "#{name} must be a positive integer"
+        end
+      end
+
+      def normalize_scoped_context(value)
+        return nil if value.nil?
+
+        if value.is_a?(Hash) || value.is_a?(Array)
+          deep_copy(value)
+        elsif value.respond_to?(:to_h)
+          deep_copy(value.to_h)
+        else
+          value
+        end
+      end
+
+      def serialize_scoped_context(value)
+        return nil if value.nil?
+
+        if value.is_a?(Hash) || value.is_a?(Array)
+          deep_copy(value)
+        elsif value.respond_to?(:to_h)
+          deep_copy(value.to_h)
+        else
+          value
+        end
+      end
+
+      def deep_copy(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), copy|
+            copy[key] = deep_copy(item)
+          end
+        when Array
+          value.map { |item| deep_copy(item) }
+        else
+          value
+        end
+      end
+
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each do |key, item|
+            deep_freeze(key)
+            deep_freeze(item)
+          end
+        when Array
+          value.each { |item| deep_freeze(item) }
+        end
+
+        value.freeze
+      end
+
+      class << self
+        private
+
+        def deep_symbolize(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, item), result|
+              result[key.to_sym] = deep_symbolize(item)
+            end
+          when Array
+            value.map { |item| deep_symbolize(item) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/persona/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Persona
+    # A compiled persona. Holds the system prompt as a Content object with
+    # trust: :system. Frozen after compilation — cannot be modified at runtime.
+    class Base
+      attr_reader :name, :content, :injection_config
+
+      def initialize(name:, system_prompt:, injection_config: {})
+        @name = name.to_sym
+        @content = Security::Gates::SystemPrompt.wrap(
+          system_prompt,
+          persona: name.to_s
+        )
+        @injection_config = injection_config.freeze
+        freeze
+      end
+
+      # Returns the system prompt as a Content object.
+      def render
+        content
+      end
+
+      def system_prompt_text
+        content.text
+      end
+
+      def inject_date?
+        injection_config.fetch(:inject_date, false)
+      end
+
+      def inject_user_context?
+        injection_config.fetch(:inject_user_context, false)
+      end
+
+      def inject_agent_context?
+        injection_config.fetch(:inject_agent_context, false)
+      end
+    end
+  end
+end

data/lib/spurline/persona/registry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Persona
+    # Per-class storage of compiled personas. Supports multiple personas
+    # per agent class, selectable at instantiation time.
+    class Registry
+      def initialize
+        @personas = {}
+      end
+
+      def register(name, persona)
+        @personas[name.to_sym] = persona
+      end
+
+      def fetch(name)
+        name = name.to_sym
+        @personas.fetch(name) do
+          raise Spurline::ConfigurationError,
+            "Persona '#{name}' is not defined. Available personas: " \
+            "#{@personas.keys.map(&:inspect).join(", ")}."
+        end
+      end
+
+      def default
+        fetch(:default)
+      rescue Spurline::ConfigurationError
+        nil
+      end
+
+      def names
+        @personas.keys
+      end
+
+      def dup_registry
+        new_registry = self.class.new
+        @personas.each { |name, persona| new_registry.register(name, persona) }
+        new_registry
+      end
+    end
+  end
+end

data/lib/spurline/secrets/resolver.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Secrets
+    class Resolver
+      def initialize(vault: nil, overrides: {})
+        @vault = vault
+        @overrides = overrides || {}
+      end
+
+      # Returns resolved value or nil.
+      def resolve(secret_name)
+        name = secret_name.to_sym
+
+        if @overrides.key?(name)
+          return resolve_override(@overrides[name])
+        end
+
+        if @vault&.key?(name)
+          return @vault.fetch(name)
+        end
+
+        cred_value = Spurline.credentials[name.to_s]
+        return cred_value if present?(cred_value)
+
+        env_value = ENV[name.to_s.upcase]
+        return env_value if present?(env_value)
+
+        nil
+      end
+
+      # Returns resolved value or raises SecretNotFoundError.
+      def resolve!(secret_name)
+        value = resolve(secret_name)
+        return value unless value.nil?
+
+        raise Spurline::SecretNotFoundError,
+          "Secret '#{secret_name}' is required but could not be resolved. " \
+          "Provide it via: agent.vault.store(:#{secret_name}, '...'), " \
+          "Spurline.credentials['#{secret_name}'] (spur credentials:edit), " \
+          "or ENV['#{secret_name.to_s.upcase}']."
+      end
+
+      private
+
+      def resolve_override(override)
+        case override
+        when Proc, Method
+          override.call
+        when Symbol, String
+          Spurline.credentials[override.to_s]
+        else
+          override
+        end
+      end
+
+      def present?(value)
+        return false if value.nil?
+        return !value.strip.empty? if value.respond_to?(:strip)
+
+        true
+      end
+    end
+  end
+end

data/lib/spurline/secrets/vault.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Secrets
+    class Vault
+      def initialize
+        @store = {}
+        @mutex = Mutex.new
+      end
+
+      def store(key, value)
+        @mutex.synchronize { @store[key.to_sym] = value }
+      end
+      alias []= store
+
+      def fetch(key, default = nil)
+        @mutex.synchronize { @store.fetch(key.to_sym, default) }
+      end
+      alias [] fetch
+
+      def key?(key)
+        @mutex.synchronize { @store.key?(key.to_sym) }
+      end
+
+      def delete(key)
+        @mutex.synchronize { @store.delete(key.to_sym) }
+      end
+
+      def clear!
+        @mutex.synchronize { @store.clear }
+      end
+
+      def keys
+        @mutex.synchronize { @store.keys }
+      end
+
+      def empty?
+        @mutex.synchronize { @store.empty? }
+      end
+    end
+  end
+end

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