spurline-core 0.3.0

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

data/lib/spurline/orchestration/ledger.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Spurline
+  module Orchestration
+    # Workflow state machine for planner/worker/judge orchestration.
+    class Ledger
+      STATES = %i[planning executing merging complete error].freeze
+
+      VALID_TRANSITIONS = {
+        planning: [:executing, :error],
+        executing: [:merging, :error],
+        merging: [:complete, :executing, :error],
+        complete: [],
+        error: [],
+      }.freeze
+
+      TASK_STATES = %i[pending assigned running complete failed].freeze
+
+      attr_reader :id, :state, :plan, :tasks, :dependency_graph,
+                  :merged_output, :metadata, :created_at
+
+      def initialize(id: SecureRandom.uuid, store: nil)
+        @id = id.to_s
+        @state = :planning
+        @plan = []
+        @tasks = {}
+        @dependency_graph = {}
+        @merged_output = {}
+        @metadata = {}
+        @created_at = Time.now.utc
+        @store = store
+      end
+
+      # @param envelope [TaskEnvelope]
+      # @return [TaskEnvelope]
+      def add_task(envelope)
+        assert_state!(:planning, "tasks can only be added during planning")
+
+        normalized = normalize_envelope(envelope)
+        task_id = normalized.task_id
+        raise Spurline::LedgerError, "task already exists: #{task_id}" if @tasks.key?(task_id)
+
+        @tasks[task_id] = {
+          envelope: normalized,
+          state: :pending,
+          worker_session_id: nil,
+          output: nil,
+          error: nil,
+        }
+        @dependency_graph[task_id] = []
+        @plan << task_id
+        persist!
+        normalized
+      end
+
+      def add_dependency(task_id, depends_on:)
+        task_id = task_id.to_s
+        depends_on = depends_on.to_s
+
+        fetch_task!(task_id)
+        fetch_task!(depends_on)
+
+        if task_id == depends_on
+          raise Spurline::LedgerError, "task cannot depend on itself: #{task_id}"
+        end
+
+        deps = (@dependency_graph[task_id] ||= [])
+        deps << depends_on unless deps.include?(depends_on)
+        persist!
+        deps
+      end
+
+      def assign_task(task_id, worker_session_id:)
+        task = fetch_task!(task_id)
+        ensure_task_state!(task_id, expected: :pending)
+
+        if worker_session_id.to_s.strip.empty?
+          raise Spurline::LedgerError, "worker_session_id is required"
+        end
+
+        task[:state] = :assigned
+        task[:worker_session_id] = worker_session_id.to_s
+        task[:error] = nil
+        persist!
+        task
+      end
+
+      def start_task(task_id)
+        task = fetch_task!(task_id)
+        ensure_task_state!(task_id, expected: :assigned)
+
+        task[:state] = :running
+        persist!
+        task
+      end
+
+      def complete_task(task_id, output:)
+        task = fetch_task!(task_id)
+        ensure_task_state_in!(task_id, expected: %i[running assigned])
+
+        task[:state] = :complete
+        task[:output] = deep_copy(output)
+        task[:error] = nil
+        persist!
+        task
+      end
+
+      def fail_task(task_id, error:)
+        task = fetch_task!(task_id)
+        ensure_task_state_in!(task_id, expected: %i[running assigned])
+
+        task[:state] = :failed
+        task[:error] = error.to_s
+        persist!
+        task
+      end
+
+      def task_status(task_id)
+        fetch_task!(task_id)[:state]
+      end
+
+      def all_tasks_complete?
+        @tasks.values.all? { |task| task[:state] == :complete }
+      end
+
+      def completed_tasks
+        select_tasks_by_state(:complete)
+      end
+
+      def pending_tasks
+        select_tasks_by_state(:pending)
+      end
+
+      # pending tasks whose dependencies are all complete
+      def unblocked_tasks
+        pending_tasks.select do |task_id, _task|
+          dependencies = @dependency_graph[task_id] || []
+          dependencies.all? { |dep_id| task_status(dep_id) == :complete }
+        end
+      end
+
+      def transition_to!(new_state)
+        target = new_state.to_sym
+
+        unless STATES.include?(target)
+          raise Spurline::LedgerError, "invalid ledger state: #{new_state.inspect}"
+        end
+
+        allowed = VALID_TRANSITIONS.fetch(@state)
+        unless allowed.include?(target)
+          raise Spurline::LedgerError, "invalid transition #{@state} -> #{target}"
+        end
+
+        @state = target
+        persist!
+        @state
+      end
+
+      def to_h
+        {
+          id: id,
+          state: state,
+          plan: deep_copy(plan),
+          tasks: serialized_tasks,
+          dependency_graph: deep_copy(dependency_graph),
+          merged_output: deep_copy(merged_output),
+          metadata: deep_copy(metadata),
+          created_at: created_at.utc.iso8601,
+        }
+      end
+
+      def self.from_h(data, store: nil)
+        hash = data || {}
+        ledger = new(id: fetch_key(hash, :id, required: true), store: store)
+
+        state = (fetch_key(hash, :state) || :planning).to_sym
+        unless STATES.include?(state)
+          raise Spurline::LedgerError, "invalid ledger state: #{state.inspect}"
+        end
+
+        plan = Array(fetch_key(hash, :plan) || []).map(&:to_s)
+        tasks = deserialize_tasks(fetch_key(hash, :tasks) || {})
+        dependency_graph = deserialize_dependency_graph(fetch_key(hash, :dependency_graph) || {})
+
+        ledger.instance_variable_set(:@state, state)
+        ledger.instance_variable_set(:@plan, plan)
+        ledger.instance_variable_set(:@tasks, tasks)
+        ledger.instance_variable_set(:@dependency_graph, dependency_graph)
+        ledger.instance_variable_set(:@merged_output, ledger.send(:deep_copy, fetch_key(hash, :merged_output) || {}))
+        ledger.instance_variable_set(:@metadata, ledger.send(:deep_copy, fetch_key(hash, :metadata) || {}))
+        ledger.instance_variable_set(:@created_at, parse_time(fetch_key(hash, :created_at)))
+
+        ledger
+      end
+
+      private
+
+      def persist!
+        @store&.save_ledger(self)
+      end
+
+      def normalize_envelope(envelope)
+        return envelope if envelope.is_a?(TaskEnvelope)
+
+        if envelope.is_a?(Hash)
+          return TaskEnvelope.from_h(envelope)
+        end
+
+        raise Spurline::LedgerError, "envelope must be a TaskEnvelope or Hash"
+      end
+
+      def fetch_task!(task_id)
+        id = task_id.to_s
+        @tasks.fetch(id) do
+          raise Spurline::LedgerError, "unknown task: #{id}"
+        end
+      end
+
+      def ensure_task_state!(task_id, expected:)
+        actual = task_status(task_id)
+        return if actual == expected
+
+        raise Spurline::LedgerError, "task #{task_id} must be #{expected}, got #{actual}"
+      end
+
+      def ensure_task_state_in!(task_id, expected:)
+        actual = task_status(task_id)
+        return if expected.include?(actual)
+
+        raise Spurline::LedgerError, "task #{task_id} must be one of #{expected.inspect}, got #{actual}"
+      end
+
+      def assert_state!(expected, message)
+        return if state == expected
+
+        raise Spurline::LedgerError, message
+      end
+
+      def select_tasks_by_state(target)
+        @tasks.each_with_object({}) do |(task_id, task), selected|
+          next unless task[:state] == target
+
+          selected[task_id] = snapshot_task(task)
+        end
+      end
+
+      def snapshot_task(task)
+        {
+          envelope: task[:envelope],
+          state: task[:state],
+          worker_session_id: task[:worker_session_id],
+          output: deep_copy(task[:output]),
+          error: task[:error],
+        }
+      end
+
+      def serialized_tasks
+        @tasks.each_with_object({}) do |(task_id, task), serialized|
+          serialized[task_id] = {
+            envelope: task[:envelope].to_h,
+            state: task[:state],
+            worker_session_id: task[:worker_session_id],
+            output: deep_copy(task[:output]),
+            error: task[:error],
+          }
+        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
+
+      class << self
+        private
+
+        def parse_time(value)
+          return Time.now.utc if value.nil?
+          return value.utc if value.respond_to?(:utc)
+
+          Time.parse(value.to_s).utc
+        end
+
+        def deserialize_tasks(raw_tasks)
+          (raw_tasks || {}).each_with_object({}) do |(task_id, task_data), deserialized|
+            task_hash = task_data || {}
+            envelope_data = fetch_key(task_hash, :envelope, required: true) do
+              raise Spurline::LedgerError, "task #{task_id} missing envelope"
+            end
+
+            envelope = envelope_data.is_a?(TaskEnvelope) ? envelope_data : TaskEnvelope.from_h(envelope_data)
+            task_state = (fetch_key(task_hash, :state) || :pending).to_sym
+
+            unless TASK_STATES.include?(task_state)
+              raise Spurline::LedgerError, "invalid task state for #{task_id}: #{task_state.inspect}"
+            end
+
+            deserialized[task_id.to_s] = {
+              envelope: envelope,
+              state: task_state,
+              worker_session_id: fetch_key(task_hash, :worker_session_id),
+              output: fetch_key(task_hash, :output),
+              error: fetch_key(task_hash, :error),
+            }
+          end
+        end
+
+        def deserialize_dependency_graph(raw_graph)
+          (raw_graph || {}).each_with_object({}) do |(task_id, deps), graph|
+            graph[task_id.to_s] = Array(deps).map(&:to_s)
+          end
+        end
+
+        def fetch_key(hash, key, required: false, &block)
+          if hash.is_a?(Hash) && hash.key?(key)
+            hash[key]
+          elsif hash.is_a?(Hash) && hash.key?(key.to_s)
+            hash[key.to_s]
+          elsif required
+            return block.call if block
+
+            raise KeyError, "missing key: #{key}"
+          end
+        end
+      end
+    end
+  end
+end