igniter 0.4.5 → 0.5.1

data/packages/igniter-app/lib/igniter/app/orchestration/policies.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      module Policies
+        class Base < Igniter::App::Operator::Policy
+          def initialize(name:, default_operation:, allowed_operations:, runtime_completion:, description:, lifecycle_operations:, operation_aliases: {}, default_routing: {})
+            operation_mapping = build_operation_mapping(allowed_operations, operation_aliases)
+
+            super(
+              name: name,
+              default_operation: default_operation,
+              allowed_operations: allowed_operations,
+              lifecycle_operations: lifecycle_operations,
+              operation_aliases: operation_aliases,
+              default_routing: default_routing,
+              operation_lifecycle: operation_mapping,
+              execution_operations: operation_mapping,
+              runtime_completion: runtime_completion,
+              description: description
+            )
+          end
+
+          private
+
+          def build_operation_mapping(allowed_operations, operation_aliases)
+            normalized_aliases = (operation_aliases || {}).each_with_object({}) do |(operation, lifecycle_operation), memo|
+              memo[operation.to_sym] = lifecycle_operation.to_sym
+            end
+
+            Array(allowed_operations).each_with_object({}) do |operation, memo|
+              normalized = operation.to_sym
+              memo[normalized] = normalized_aliases.fetch(normalized, normalized)
+            end
+          end
+        end
+
+        class InteractiveSessionPolicy < Base
+          def initialize
+            super(
+              name: :interactive_session,
+              default_operation: :wake,
+              allowed_operations: %i[wake handoff complete dismiss],
+              lifecycle_operations: %i[acknowledge resolve dismiss],
+              operation_aliases: {
+                wake: :acknowledge,
+                handoff: :acknowledge,
+                complete: :resolve
+              },
+              default_routing: {
+                queue: "interactive-sessions",
+                channel: "inbox://interactive-sessions"
+              },
+              runtime_completion: :optional,
+              description: "operator-facing interactive session; wake or hand off the session first, complete it only when the conversation is actually done"
+            )
+          end
+        end
+
+        class ManualCompletionPolicy < Base
+          def initialize
+            super(
+              name: :manual_completion,
+              default_operation: :approve,
+              allowed_operations: %i[approve handoff dismiss],
+              lifecycle_operations: %i[acknowledge resolve dismiss],
+              operation_aliases: {
+                approve: :resolve,
+                handoff: :acknowledge
+              },
+              default_routing: {
+                queue: "manual-completions",
+                channel: "inbox://manual-completions"
+              },
+              runtime_completion: :required,
+              description: "manual completion step; approve when the operator has an explicit completion value, or hand it off without completing runtime state yet"
+            )
+          end
+        end
+
+        class SingleTurnCompletionPolicy < Base
+          def initialize
+            super(
+              name: :single_turn_completion,
+              default_operation: :complete,
+              allowed_operations: %i[complete dismiss],
+              lifecycle_operations: %i[resolve dismiss],
+              operation_aliases: {
+                complete: :resolve
+              },
+              default_routing: {
+                queue: "single-turn-completions",
+                channel: "inbox://single-turn-completions"
+              },
+              runtime_completion: :required,
+              description: "single-turn streamed step; complete it when the one-shot result is ready, or dismiss it when the workflow intentionally abandons the step"
+            )
+          end
+        end
+
+        class DeferredReplyPolicy < Base
+          def initialize
+            super(
+              name: :deferred_reply,
+              default_operation: :reply,
+              allowed_operations: %i[reply handoff dismiss],
+              lifecycle_operations: %i[acknowledge resolve dismiss],
+              operation_aliases: {
+                reply: :resolve,
+                handoff: :acknowledge
+              },
+              default_routing: {
+                queue: "deferred-replies",
+                channel: "inbox://deferred-replies"
+              },
+              runtime_completion: :optional,
+              description: "deferred reply step; reply when the answer arrives, or hand the waiting work to an operator without completing the runtime session yet"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/orchestration/policy_registry.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class PolicyRegistry
+        class << self
+          def register(action, policy = nil, queue: nil, &block)
+            resolved_policy = policy || block
+            raise ArgumentError, "orchestration policy registration requires a policy object or builder" unless resolved_policy
+
+            registry[registry_key(action, queue: queue)] = resolved_policy
+          end
+
+          def fetch(action, queue: nil)
+            if queue
+              keyed = registry_key(action, queue: queue)
+              return resolve_policy(registry.fetch(keyed)) if registry.key?(keyed)
+            end
+
+            resolved = registry.fetch(registry_key(action))
+            resolve_policy(resolved)
+          end
+
+          def registered?(action, queue: nil)
+            registry.key?(registry_key(action, queue: queue))
+          end
+
+          def actions
+            registry.keys.map { |key| key[:action] }.uniq
+          end
+
+          private
+
+          def registry
+            @registry ||= {}
+          end
+
+          def resolve_policy(resolved)
+            resolved.respond_to?(:call) ? resolved.call : resolved
+          end
+
+          def normalize_action(action)
+            action.to_sym
+          end
+
+          def normalize_queue(queue)
+            return nil if queue.nil?
+
+            queue.to_s
+          end
+
+          def registry_key(action, queue: nil)
+            {
+              action: normalize_action(action),
+              queue: normalize_queue(queue)
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/orchestration/result.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class Result
+        attr_reader :app_class, :opened, :existing
+
+        def initialize(app_class:, opened:, existing:)
+          @app_class = app_class
+          @opened = Array(opened).map { |entry| entry.freeze }.freeze
+          @existing = Array(existing).map { |entry| entry.freeze }.freeze
+          freeze
+        end
+
+        def status
+          return :opened if opened.any? && existing.empty?
+          return :existing if existing.any? && opened.empty?
+          return :partial if opened.any? && existing.any?
+
+          :noop
+        end
+
+        def opened?
+          !opened.empty?
+        end
+
+        def existing?
+          !existing.empty?
+        end
+
+        def to_h
+          {
+            app: app_class.name,
+            status: status,
+            opened: opened,
+            existing: existing
+          }
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/orchestration/routing_registry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class RoutingRegistry
+        class << self
+          def register(action, routing = nil, &block)
+            resolved_routing = routing || block
+            raise ArgumentError, "orchestration routing registration requires a routing hash or builder" unless resolved_routing
+
+            registry[normalize_action(action)] = resolved_routing
+          end
+
+          def fetch(action)
+            resolved = registry.fetch(normalize_action(action))
+            normalize_routing(resolved.respond_to?(:call) ? resolved.call : resolved)
+          end
+
+          def registered?(action)
+            registry.key?(normalize_action(action))
+          end
+
+          private
+
+          def registry
+            @registry ||= {}
+          end
+
+          def normalize_action(action)
+            action.to_sym
+          end
+
+          def normalize_routing(routing)
+            routing.each_with_object({}) do |(key, value), memo|
+              memo[key.to_sym] = value
+            end.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/orchestration/runner.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class Runner
+        def initialize(app_class:)
+          @app_class = app_class
+        end
+
+        def run(plan, graph: nil, execution_id: nil, execution: nil)
+          inbox = app_class.orchestration_inbox
+          opened = []
+          existing = []
+          sessions_by_node = index_sessions_by_node(execution)
+
+          plan.followup_request.actions.each do |action|
+            existing_item = inbox.find_active(action[:id])
+            if existing_item
+              existing << existing_item.merge(status: :existing)
+              next
+            end
+
+            opened << inbox.open(
+              action,
+              source: plan.source,
+              graph: graph,
+              execution_id: execution_id,
+              session: sessions_by_node[action[:node].to_sym]
+            )
+          end
+
+          Result.new(app_class: app_class, opened: opened, existing: existing)
+        end
+
+        private
+
+        attr_reader :app_class
+
+        def index_sessions_by_node(execution)
+          return {} unless execution
+
+          execution.agent_sessions.each_with_object({}) do |session, memo|
+            memo[session.node_name.to_sym] = session
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/orchestration/runtime_event_query.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Orchestration
+      class RuntimeEventQuery
+        include Enumerable
+
+        FILTERABLE_DIMENSIONS = %i[
+          node event event_class source status terminal actor origin
+          requested_operation lifecycle_operation execution_operation
+        ].freeze
+        ORDERABLE_DIMENSIONS = %i[
+          node event event_class source status timestamp actor origin
+          requested_operation lifecycle_operation execution_operation
+        ].freeze
+
+        def initialize(events)
+          @events = Array(events).map(&:dup).freeze
+          @filters = [].freeze
+          @orderings = [].freeze
+          @limit_count = nil
+          freeze
+        end
+
+        def node(*nodes)
+          normalized = nodes.map(&:to_sym)
+          add_filter { |event| normalized.include?(event[:node]) }
+        end
+
+        def event(*events)
+          normalized = events.map(&:to_sym)
+          add_filter { |entry| normalized.include?(entry[:event]) }
+        end
+
+        def event_class(*classes)
+          normalized = classes.map(&:to_sym)
+          add_filter { |entry| normalized.include?(entry[:event_class]) }
+        end
+
+        def source(*sources)
+          normalized = sources.map(&:to_sym)
+          add_filter { |entry| normalized.include?(entry[:source]) }
+        end
+
+        def status(*statuses)
+          normalized = statuses.map(&:to_sym)
+          add_filter { |entry| normalized.include?(entry[:status]) }
+        end
+
+        def terminal(value = true)
+          expected = !!value
+          add_filter { |entry| entry[:terminal] == expected }
+        end
+
+        def actor(*actors)
+          normalized = actors.map(&:to_s)
+          add_filter { |entry| normalized.include?(entry[:actor].to_s) }
+        end
+
+        def origin(*origins)
+          normalized = origins.map(&:to_s)
+          add_filter { |entry| normalized.include?(entry[:origin].to_s) }
+        end
+
+        def requested_operation(*operations)
+          normalized = operations.map(&:to_sym)
+          add_filter { |entry| normalized.include?(entry[:requested_operation]) }
+        end
+
+        def lifecycle_operation(*operations)
+          normalized = operations.map(&:to_sym)
+          add_filter { |entry| normalized.include?(entry[:lifecycle_operation]) }
+        end
+
+        def execution_operation(*operations)
+          normalized = operations.map(&:to_sym)
+          add_filter { |entry| normalized.include?(entry[:execution_operation]) }
+        end
+
+        def where(&block)
+          raise ArgumentError, "where requires a block" unless block
+
+          add_filter(&block)
+        end
+
+        def order_by(dimension, direction: :asc)
+          raise ArgumentError, "direction must be :asc or :desc" unless %i[asc desc].include?(direction)
+          unless ORDERABLE_DIMENSIONS.include?(dimension) || dimension.respond_to?(:call)
+            raise ArgumentError, "Unknown ordering dimension: #{dimension.inspect}. Use one of #{ORDERABLE_DIMENSIONS.inspect} or a Proc."
+          end
+
+          clone_query do |query|
+            query.instance_variable_set(:@orderings, (@orderings + [{ dimension: dimension, direction: direction }]).freeze)
+          end
+        end
+
+        def limit(count)
+          clone_query { |query| query.instance_variable_set(:@limit_count, count) }
+        end
+
+        def facet(dimension)
+          raise ArgumentError, "Unknown facet dimension: #{dimension.inspect}. Use one of #{FILTERABLE_DIMENSIONS.inspect}" unless FILTERABLE_DIMENSIONS.include?(dimension)
+
+          to_a.each_with_object(Hash.new(0)) do |entry, memo|
+            value = entry[dimension]
+            next if value.nil?
+
+            memo[value] += 1
+          end.freeze
+        end
+
+        def summary
+          entries = to_a
+
+          {
+            total: entries.size,
+            terminal: entries.count { |entry| entry[:terminal] },
+            runtime_events: entries.count { |entry| entry[:event_class] == :runtime },
+            operator_events: entries.count { |entry| entry[:event_class] == :operator },
+            by_node: facet(:node),
+            by_event: facet(:event),
+            by_event_class: facet(:event_class),
+            by_source: facet(:source),
+            by_status: facet(:status),
+            by_lifecycle_operation: facet(:lifecycle_operation),
+            by_execution_operation: facet(:execution_operation),
+            latest_event: entries.last&.dup,
+            latest_per_node: latest_per_node(entries)
+          }.freeze
+        end
+
+        def to_h(limit: 20)
+          {
+            summary: summary,
+            events: order_by(:timestamp).limit(limit).to_a,
+            recent_events: order_by(:timestamp).to_a.last(limit)
+          }.freeze
+        end
+
+        def each(&block)
+          to_a.each(&block)
+        end
+
+        def to_a
+          entries = @events.select do |entry|
+            @filters.all? { |filter| filter.call(entry) }
+          end
+
+          ordered = apply_orderings(entries)
+          @limit_count ? ordered.first(@limit_count) : ordered
+        end
+
+        private
+
+        def add_filter(&block)
+          clone_query do |query|
+            query.instance_variable_set(:@filters, (@filters + [block]).freeze)
+          end
+        end
+
+        def clone_query
+          self.class.allocate.tap do |query|
+            query.instance_variable_set(:@events, @events)
+            query.instance_variable_set(:@filters, @filters)
+            query.instance_variable_set(:@orderings, @orderings)
+            query.instance_variable_set(:@limit_count, @limit_count)
+            yield(query)
+            query.freeze
+          end
+        end
+
+        def apply_orderings(entries)
+          return entries if @orderings.empty?
+
+          @orderings.reverse_each.reduce(entries) do |ordered, ordering|
+            dimension = ordering.fetch(:dimension)
+            direction = ordering.fetch(:direction)
+
+            sorted = ordered.sort_by do |entry|
+              value = dimension.respond_to?(:call) ? dimension.call(entry) : entry[dimension]
+              value.nil? ? [1, nil] : [0, normalize_order_value(value)]
+            end
+            direction == :desc ? sorted.reverse : sorted
+          end
+        end
+
+        def latest_per_node(entries)
+          entries.each_with_object({}) do |entry, memo|
+            memo[entry[:node]] = entry.dup if entry[:node]
+          end.freeze
+        end
+
+        def normalize_order_value(value)
+          case value
+          when Time
+            value.utc.iso8601(6)
+          else
+            value.to_s
+          end
+        end
+      end
+    end
+  end
+end