spurline-deploy 0.3.0

data/lib/spurline/memory/manager.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    # Orchestrates short-term and long-term memory stores.
+    class Manager
+      attr_reader :short_term, :long_term, :episodic
+
+      def initialize(config: {})
+        window = config.fetch(:short_term, {}).fetch(:window, ShortTerm::DEFAULT_WINDOW)
+        @short_term = ShortTerm.new(window: window)
+        @long_term = build_long_term_store(config.fetch(:long_term, nil))
+        @episodic = build_episodic_store(config.fetch(:episodic, nil))
+      end
+
+      def add_turn(turn)
+        evicted_before = short_term.last_evicted
+        short_term.add_turn(turn)
+
+        evicted_turn = short_term.last_evicted
+        if long_term && evicted_turn && !evicted_turn.equal?(evicted_before)
+          persist_to_long_term!(evicted_turn)
+        end
+      end
+
+      def recent_turns(n = nil)
+        short_term.recent(n)
+      end
+
+      def turn_count
+        short_term.size
+      end
+
+      def recall(query:, limit: 5)
+        return [] unless long_term
+
+        long_term.retrieve(query: query, limit: limit)
+      end
+
+      def clear!
+        short_term.clear!
+        long_term&.clear!
+        episodic&.clear!
+      end
+
+      # Whether any turns have been evicted from the window.
+      # Useful for determining if summarization should kick in.
+      def window_overflowed?
+        !short_term.last_evicted.nil?
+      end
+
+      def record_episode(type:, content:, metadata: {}, turn_number: nil, parent_episode_id: nil, timestamp: Time.now)
+        return nil unless episodic
+
+        episodic.record(
+          type: type,
+          content: content,
+          metadata: metadata,
+          turn_number: turn_number,
+          parent_episode_id: parent_episode_id,
+          timestamp: timestamp
+        )
+      end
+
+      def restore_episodes(serialized_episodes)
+        return unless episodic
+
+        episodic.restore(serialized_episodes)
+      end
+
+      private
+
+      def build_long_term_store(config)
+        return nil unless config
+
+        adapter = config[:adapter]
+        case adapter
+        when :postgres
+          embedder = build_embedder(config)
+          LongTerm::Postgres.new(connection_string: config[:connection_string], embedder: embedder)
+        when nil
+          nil
+        else
+          return adapter if adapter.respond_to?(:store) && adapter.respond_to?(:retrieve)
+
+          raise Spurline::ConfigurationError,
+            "Unknown long-term memory adapter: #{adapter.inspect}."
+        end
+      end
+
+      def build_embedder(config)
+        model = config[:embedding_model] || config[:embedder]
+
+        case model
+        when :openai
+          Embedder::OpenAI.new
+        when nil
+          raise Spurline::ConfigurationError,
+            "Long-term memory requires an embedding_model. " \
+            "Example: memory :long_term, adapter: :postgres, embedding_model: :openai"
+        else
+          return model if model.respond_to?(:embed) && model.respond_to?(:dimensions)
+
+          raise Spurline::ConfigurationError,
+            "Unknown embedding model: #{model.inspect}."
+        end
+      end
+
+      def persist_to_long_term!(turn)
+        text_parts = []
+        text_parts << extract_text(turn.input) if turn.input
+        text_parts << extract_text(turn.output) if turn.output
+        content_text = text_parts.join("\n")
+        return if content_text.strip.empty?
+
+        long_term.store(content: content_text, metadata: { turn_number: turn.number })
+      end
+
+      def build_episodic_store(config)
+        enabled = case config
+                  when nil
+                    true
+                  when true, false
+                    config
+                  when Hash
+                    config.fetch(:enabled, true)
+                  else
+                    !!config
+                  end
+
+        episodes = config.is_a?(Hash) ? config.fetch(:episodes, []) : []
+        EpisodicStore.new(enabled: enabled, episodes: episodes)
+      end
+
+      def extract_text(value)
+        case value
+        when Security::Content
+          value.text
+        when String
+          value
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/short_term.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    # Sliding window of recent turns. Holds Turn objects with their Content
+    # (input/output) carrying inherited trust levels.
+    #
+    # When the window overflows, oldest turns are evicted. The last evicted
+    # turn is available via #last_evicted for potential summarization.
+    class ShortTerm
+      DEFAULT_WINDOW = 20
+
+      attr_reader :window_size, :last_evicted
+
+      def initialize(window: DEFAULT_WINDOW)
+        @window_size = window
+        @turns = []
+        @last_evicted = nil
+      end
+
+      def add_turn(turn)
+        @turns << turn
+        trim!
+      end
+
+      # Returns recent turns as an array, most recent last.
+      def recent(n = nil)
+        n ? @turns.last(n) : @turns.dup
+      end
+
+      def size
+        @turns.length
+      end
+
+      def full?
+        @turns.length >= @window_size
+      end
+
+      def empty?
+        @turns.empty?
+      end
+
+      def clear!
+        @turns.clear
+        @last_evicted = nil
+      end
+
+      private
+
+      def trim!
+        while @turns.length > window_size
+          @last_evicted = @turns.shift
+        end
+      end
+    end
+  end
+end

data/lib/spurline/orchestration/agent_spawner.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Orchestration
+    # Creates and runs child agents with permission-safe delegation.
+    #
+    # The setuid rule: child permissions are always <= parent permissions.
+    # Child scope inherits from the parent unless explicitly narrowed.
+    class AgentSpawner
+      def initialize(parent_agent:)
+        @parent_agent = parent_agent
+        @parent_session = parent_agent.session
+        @parent_scope = extract_scope(parent_agent)
+        @parent_permissions = extract_permissions(parent_agent)
+      end
+
+      # ASYNC-READY: spawns and runs a child agent, which is a blocking operation
+      def spawn(agent_class, input:, permissions: nil, scope: nil, &block)
+        validate_agent_class!(agent_class)
+
+        effective_permissions = compute_effective_permissions(permissions)
+        effective_scope = compute_effective_scope(scope)
+
+        child_agent = build_child_agent(
+          agent_class: agent_class,
+          permissions: effective_permissions,
+          scope: effective_scope
+        )
+
+        child_agent.session.metadata[:parent_session_id] = @parent_session.id
+        child_agent.session.metadata[:parent_agent_class] = @parent_agent.class.name
+
+        fire_parent_hook(:on_child_spawn, child_agent, agent_class)
+
+        begin
+          child_agent.run(input) do |chunk|
+            block&.call(chunk)
+          end
+
+          fire_parent_hook(:on_child_complete, child_agent, child_agent.session)
+        rescue Spurline::AgentError => e
+          fire_parent_hook(:on_child_error, child_agent, e)
+          raise Spurline::SpawnError,
+            "Child agent #{agent_class.name || agent_class} failed: #{e.message}. " \
+            "Parent session: #{@parent_session.id}, child session: #{child_agent.session.id}."
+        end
+
+        child_agent.session
+      end
+
+      private
+
+      def validate_agent_class!(agent_class)
+        unless agent_class.is_a?(Class) && agent_class <= Spurline::Agent
+          raise Spurline::ConfigurationError,
+            "spawn_agent requires a class that inherits from Spurline::Agent. " \
+            "Got: #{agent_class.inspect}"
+        end
+      end
+
+      def compute_effective_permissions(child_permissions)
+        return deep_copy(@parent_permissions) if child_permissions.nil?
+
+        PermissionIntersection.validate_no_escalation!(
+          @parent_permissions,
+          child_permissions
+        )
+
+        PermissionIntersection.compute(
+          @parent_permissions,
+          child_permissions
+        )
+      end
+
+      def compute_effective_scope(child_scope)
+        return @parent_scope if child_scope.nil?
+        return child_scope if @parent_scope.nil?
+
+        if child_scope.is_a?(Spurline::Tools::Scope)
+          validate_scope_subset!(child_scope) if @parent_scope
+          child_scope
+        elsif child_scope.is_a?(Hash)
+          @parent_scope.narrow(child_scope)
+        else
+          raise Spurline::ConfigurationError,
+            "scope must be a Spurline::Tools::Scope or a Hash of constraints. " \
+            "Got: #{child_scope.class} (#{child_scope.inspect})"
+        end
+      end
+
+      def validate_scope_subset!(child_scope)
+        return if child_scope.subset_of?(@parent_scope)
+
+        raise Spurline::ScopeViolationError,
+          "Child scope '#{child_scope.id}' is wider than parent scope '#{@parent_scope.id}'. " \
+          "A spawned agent cannot access resources outside the parent's scope. " \
+          "Narrow the child scope or widen the parent scope."
+      end
+
+      def build_child_agent(agent_class:, permissions:, scope:)
+        child_agent = agent_class.new(
+          user: @parent_session.user,
+          scope: scope
+        )
+
+        inject_effective_permissions!(child_agent, permissions)
+        child_agent
+      end
+
+      def inject_effective_permissions!(child_agent, permissions)
+        return if permissions.nil?
+
+        tool_runner = child_agent.instance_variable_get(:@tool_runner)
+        return unless tool_runner
+
+        existing_permissions = tool_runner.instance_variable_get(:@permissions) || {}
+        merged_permissions = existing_permissions.merge(permissions)
+        tool_runner.instance_variable_set(:@permissions, merged_permissions)
+      end
+
+      def extract_scope(agent)
+        agent.instance_variable_get(:@scope)
+      end
+
+      def extract_permissions(agent)
+        klass = agent.class
+        return {} unless klass.respond_to?(:permissions_config)
+
+        klass.permissions_config
+      end
+
+      def fire_parent_hook(hook_type, *args)
+        hooks = @parent_agent.class.hooks_config[hook_type] || []
+        hooks.each { |hook_block| hook_block.call(*args) }
+      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
+    end
+  end
+end

data/lib/spurline/orchestration/judge.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Orchestration
+    # Stateless evaluator that decides whether worker output satisfies a task.
+    class Judge
+      STRATEGIES = %i[structured llm_eval custom].freeze
+
+      Verdict = Struct.new(:decision, :reason, :feedback, keyword_init: true) do
+        def accepted?
+          decision == :accept
+        end
+
+        def rejected?
+          decision == :reject
+        end
+
+        def needs_revision?
+          decision == :revise
+        end
+      end
+
+      def initialize(strategy: :structured)
+        @strategy = strategy.to_sym
+        validate_strategy!(@strategy)
+      end
+
+      # ASYNC-READY: evaluate may call an LLM for :llm_eval strategy.
+      def evaluate(envelope:, output:, scheduler: Adapters::Scheduler::Sync.new, &custom_evaluator)
+        scheduler.run do
+          case @strategy
+          when :structured
+            evaluate_structured(envelope, output)
+          when :llm_eval
+            Verdict.new(
+              decision: :accept,
+              reason: "LLM evaluator stub",
+              feedback: "llm_eval strategy is a placeholder in M2.4"
+            )
+          when :custom
+            evaluate_custom(envelope, output, &custom_evaluator)
+          end
+        end
+      end
+
+      private
+
+      def evaluate_structured(envelope, output)
+        output_text = normalize_output(output)
+        criteria = envelope.acceptance_criteria.map(&:to_s)
+
+        missing = criteria.reject do |criterion|
+          output_text.downcase.include?(criterion.downcase)
+        end
+
+        if missing.empty?
+          Verdict.new(decision: :accept, reason: "All acceptance criteria matched", feedback: nil)
+        else
+          Verdict.new(
+            decision: :reject,
+            reason: "Missing acceptance criteria",
+            feedback: "Missing: #{missing.join(", ")}"
+          )
+        end
+      end
+
+      def evaluate_custom(envelope, output, &block)
+        raise ArgumentError, "custom evaluator block is required" unless block
+
+        result = block.call(envelope, output)
+
+        case result
+        when Verdict
+          result
+        when true
+          Verdict.new(decision: :accept, reason: "custom evaluator accepted", feedback: nil)
+        when false
+          Verdict.new(decision: :reject, reason: "custom evaluator rejected", feedback: nil)
+        when Hash
+          decision = (result[:decision] || result["decision"] || :reject).to_sym
+          reason = result[:reason] || result["reason"] || "custom evaluator result"
+          feedback = result[:feedback] || result["feedback"]
+          Verdict.new(decision: decision, reason: reason, feedback: feedback)
+        else
+          raise ArgumentError, "custom evaluator must return Verdict, boolean, or hash"
+        end
+      end
+
+      def validate_strategy!(strategy)
+        return if STRATEGIES.include?(strategy)
+
+        raise Spurline::ConfigurationError, "invalid judge strategy: #{strategy.inspect}"
+      end
+
+      def normalize_output(output)
+        case output
+        when String
+          output
+        when Hash
+          output.map { |key, value| "#{key}: #{value}" }.join("\n")
+        when Array
+          output.join("\n")
+        else
+          output.to_s
+        end
+      end
+    end
+  end
+end

data/lib/spurline/orchestration/ledger/store/base.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Orchestration
+    class Ledger
+      module Store
+        # Abstract interface for ledger storage adapters.
+        class Base
+          def save_ledger(_ledger)
+            raise NotImplementedError, "#{self.class.name} must implement #save_ledger"
+          end
+
+          def load_ledger(_id)
+            raise NotImplementedError, "#{self.class.name} must implement #load_ledger"
+          end
+
+          def exists?(_id)
+            raise NotImplementedError, "#{self.class.name} must implement #exists?"
+          end
+
+          def delete(_id)
+            raise NotImplementedError, "#{self.class.name} must implement #delete"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/orchestration/ledger/store/memory.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Orchestration
+    class Ledger
+      module Store
+        # In-memory ledger store for tests and local development.
+        class Memory < Base
+          def initialize
+            @ledgers = {}
+            @mutex = Mutex.new
+          end
+
+          def save_ledger(ledger)
+            @mutex.synchronize do
+              @ledgers[ledger.id] = ledger.to_h
+            end
+          end
+
+          def load_ledger(id)
+            payload = @mutex.synchronize { @ledgers[id.to_s] }
+            raise Spurline::LedgerError, "ledger not found: #{id}" if payload.nil?
+
+            Spurline::Orchestration::Ledger.from_h(payload, store: self)
+          end
+
+          def exists?(id)
+            @mutex.synchronize { @ledgers.key?(id.to_s) }
+          end
+
+          def delete(id)
+            @mutex.synchronize { @ledgers.delete(id.to_s) }
+          end
+
+          def size
+            @mutex.synchronize { @ledgers.size }
+          end
+
+          def clear!
+            @mutex.synchronize { @ledgers.clear }
+          end
+
+          def ids
+            @mutex.synchronize { @ledgers.keys.dup }
+          end
+        end
+      end
+    end
+  end
+end