igniter 0.5.0 → 0.5.1

data/packages/igniter-app/lib/igniter/app/observability/operator_overview_handler.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Igniter
+  class App
+    module Observability
+      class OperatorOverviewHandler
+        DEFAULT_LIMIT = 20
+        LIST_FILTERS = %i[
+          id status action node combined_state interaction reason policy lane queue
+          channel assignee phase reply_mode mode tool_loop_status ownership
+          session_lifecycle_state
+          latest_action_actor latest_action_origin latest_action_source
+        ].freeze
+        BOOLEAN_FILTERS = %i[
+          actionable attention_required resumable with_session
+          with_inbox_item with_token handed_off interactive
+          terminal continuable routed
+        ].freeze
+        EVENT_LIST_FILTERS = %i[
+          node event event_class source status actor origin
+          requested_operation lifecycle_operation execution_operation
+        ].freeze
+        EVENT_BOOLEAN_FILTERS = %i[terminal].freeze
+        CREDENTIAL_LIST_FILTERS = %i[
+          event status credential_key policy_name source reason
+          node target_node actor origin
+        ].freeze
+        CREDENTIAL_FILTER_ALIASES = {
+          policy_name: :credential_policy
+        }.freeze
+        CREDENTIAL_ORDERABLE_FIELDS = %i[
+          timestamp event status credential_key policy_name source reason
+          node target_node actor origin
+        ].freeze
+        CREDENTIAL_REQUEST_LIST_FILTERS = %i[
+          latest_event status credential_key policy_name source reason
+          node target_node actor origin request_id lease_id requested_scope credential_provider
+        ].freeze
+        CREDENTIAL_REQUEST_FILTER_ALIASES = {
+          policy_name: :credential_request_policy
+        }.freeze
+        CREDENTIAL_REQUEST_ORDERABLE_FIELDS = %i[
+          latest_at latest_event status credential_key policy_name source reason
+          node target_node actor origin request_id lease_id requested_scope credential_provider requested_at
+        ].freeze
+
+        def initialize(app_class:, limit: DEFAULT_LIMIT, store: nil)
+          @app_class = app_class
+          @default_limit = limit
+          @store = store
+        end
+
+        def call(params:, body:, headers:, env:, raw_body:, config:) # rubocop:disable Lint/UnusedMethodArgument
+          request_params = query_params(env).merge(symbolize_keys(params))
+          limit = normalize_limit(request_params.delete(:limit))
+          filters = extract_filters(request_params)
+          order_by = normalize_order_by(request_params.delete(:order_by))
+          direction = normalize_direction(request_params.delete(:direction))
+          event_limit = normalize_limit(request_params.delete(:event_limit) || limit)
+          event_filters = extract_event_filters(request_params)
+          event_order_by = normalize_event_order_by(request_params.delete(:event_order_by))
+          event_direction = normalize_direction(request_params.delete(:event_direction))
+          credential_limit = normalize_limit(request_params.delete(:credential_limit) || event_limit)
+          credential_filters = extract_credential_filters(request_params)
+          credential_order_by = normalize_credential_order_by(request_params.delete(:credential_order_by))
+          credential_direction = normalize_direction(request_params.delete(:credential_direction))
+          credential_request_limit = normalize_limit(request_params.delete(:credential_request_limit) || credential_limit)
+          credential_request_filters = extract_credential_request_filters(request_params)
+          credential_request_order_by = normalize_credential_request_order_by(request_params.delete(:credential_request_order_by))
+          credential_request_direction = normalize_direction(request_params.delete(:credential_request_direction))
+
+          overview =
+            if request_params.key?(:graph) || request_params.key?(:execution_id)
+              graph = request_params[:graph]
+              execution_id = request_params[:execution_id]
+
+              validate_execution_scope!(graph: graph, execution_id: execution_id)
+              app_class.operator_overview_for_execution(
+                graph: graph,
+                execution_id: execution_id,
+                limit: limit,
+                store: resolved_store(config),
+                filters: filters,
+                order_by: order_by,
+                direction: direction,
+                event_filters: event_filters,
+                event_order_by: event_order_by,
+                event_direction: event_direction,
+                event_limit: event_limit,
+                credential_filters: credential_filters,
+                credential_order_by: credential_order_by,
+                credential_direction: credential_direction,
+                credential_limit: credential_limit,
+                credential_request_filters: credential_request_filters,
+                credential_request_order_by: credential_request_order_by,
+                credential_request_direction: credential_request_direction,
+                credential_request_limit: credential_request_limit
+              )
+            else
+              app_class.operator_overview(
+                limit: limit,
+                filters: filters,
+                order_by: order_by,
+                direction: direction,
+                event_filters: event_filters,
+                event_order_by: event_order_by,
+                event_direction: event_direction,
+                event_limit: event_limit,
+                credential_filters: credential_filters,
+                credential_order_by: credential_order_by,
+                credential_direction: credential_direction,
+                credential_limit: credential_limit,
+                credential_request_filters: credential_request_filters,
+                credential_request_order_by: credential_request_order_by,
+                credential_request_direction: credential_request_direction,
+                credential_request_limit: credential_request_limit
+              ).merge(
+                scope: { mode: :app }.freeze
+              ).freeze
+            end
+
+          json_response(200, overview)
+        rescue ArgumentError => e
+          json_response(400, error: e.message)
+        rescue Igniter::ResolutionError => e
+          json_response(404, error: e.message)
+        rescue Igniter::Error => e
+          json_response(422, error: e.message)
+        end
+
+        private
+
+        attr_reader :app_class, :default_limit, :store
+
+        def query_params(env)
+          URI.decode_www_form(env.fetch("QUERY_STRING", "").to_s).each_with_object({}) do |(key, value), memo|
+            memo[key.to_sym] = value
+          end
+        end
+
+        def symbolize_keys(hash)
+          hash.to_h.each_with_object({}) do |(key, value), memo|
+            memo[key.to_sym] = value
+          end
+        end
+
+        def normalize_limit(value)
+          return default_limit if value.nil? || value.to_s.empty?
+
+          limit = Integer(value)
+          raise ArgumentError, "limit must be greater than or equal to 1" if limit < 1
+
+          limit
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "limit must be an integer greater than or equal to 1"
+        end
+
+        def extract_filters(request_params)
+          filters = {}
+
+          LIST_FILTERS.each do |name|
+            next unless request_params.key?(name)
+
+            values = normalize_list(request_params.delete(name), symbolize: symbol_filter?(name))
+            filters[name] = values if values.any?
+          end
+
+          BOOLEAN_FILTERS.each do |name|
+            next unless request_params.key?(name)
+
+            filters[name] = normalize_boolean(request_params.delete(name), name)
+          end
+
+          filters.freeze
+        end
+
+        def extract_event_filters(request_params)
+          filters = {}
+
+          EVENT_LIST_FILTERS.each do |name|
+            param_name = :"event_#{name}"
+            next unless request_params.key?(param_name)
+
+            values = normalize_list(request_params.delete(param_name), symbolize: event_symbol_filter?(name))
+            filters[name] = values if values.any?
+          end
+
+          EVENT_BOOLEAN_FILTERS.each do |name|
+            param_name = :"event_#{name}"
+            next unless request_params.key?(param_name)
+
+            filters[name] = normalize_boolean(request_params.delete(param_name), param_name)
+          end
+
+          filters.freeze
+        end
+
+        def extract_credential_filters(request_params)
+          filters = {}
+
+          CREDENTIAL_LIST_FILTERS.each do |name|
+            param_name =
+              if CREDENTIAL_FILTER_ALIASES.key?(name)
+                alias_name = CREDENTIAL_FILTER_ALIASES.fetch(name)
+                request_params.key?(alias_name) ? alias_name : :"credential_#{name}"
+              else
+                :"credential_#{name}"
+              end
+            next unless request_params.key?(param_name)
+
+            values = normalize_list(request_params.delete(param_name), symbolize: credential_symbol_filter?(name))
+            filters[name] = values if values.any?
+          end
+
+          filters.freeze
+        end
+
+        def extract_credential_request_filters(request_params)
+          filters = {}
+
+          CREDENTIAL_REQUEST_LIST_FILTERS.each do |name|
+            param_name =
+              if CREDENTIAL_REQUEST_FILTER_ALIASES.key?(name)
+                alias_name = CREDENTIAL_REQUEST_FILTER_ALIASES.fetch(name)
+                request_params.key?(alias_name) ? alias_name : :"credential_request_#{name}"
+              else
+                :"credential_request_#{name}"
+              end
+            next unless request_params.key?(param_name)
+
+            values = normalize_list(request_params.delete(param_name), symbolize: credential_request_symbol_filter?(name))
+            filters[name] = values if values.any?
+          end
+
+          filters.freeze
+        end
+
+        def symbol_filter?(name)
+          !%i[
+            id queue channel assignee latest_action_actor latest_action_origin
+            latest_action_source
+          ].include?(name)
+        end
+
+        def event_symbol_filter?(name)
+          !%i[actor origin].include?(name)
+        end
+
+        def credential_symbol_filter?(name)
+          !%i[node target_node actor origin].include?(name)
+        end
+
+        def credential_request_symbol_filter?(name)
+          !%i[node target_node actor origin request_id lease_id].include?(name)
+        end
+
+        def normalize_list(value, symbolize: false)
+          Array(value)
+            .flat_map { |entry| entry.to_s.split(",") }
+            .map(&:strip)
+            .reject(&:empty?)
+            .map { |entry| symbolize ? entry.tr(" ", "_").to_sym : entry }
+        end
+
+        def normalize_boolean(value, name)
+          case value.to_s.strip.downcase
+          when "1", "true", "yes", "y", "on"
+            true
+          when "0", "false", "no", "n", "off"
+            false
+          else
+            raise ArgumentError, "#{name} must be a boolean value"
+          end
+        end
+
+        def normalize_order_by(value)
+          return nil if value.nil? || value.to_s.strip.empty?
+
+          order_by = value.to_s.strip.tr(" ", "_").to_sym
+          allowed = Igniter::App::Orchestration::OperatorQuery::ORDERABLE_DIMENSIONS
+          raise ArgumentError, "order_by must be one of #{allowed.inspect}" unless allowed.include?(order_by)
+
+          order_by
+        end
+
+        def normalize_direction(value)
+          return :asc if value.nil? || value.to_s.strip.empty?
+
+          direction = value.to_s.strip.downcase.to_sym
+          raise ArgumentError, "direction must be asc or desc" unless %i[asc desc].include?(direction)
+
+          direction
+        end
+
+        def normalize_event_order_by(value)
+          return nil if value.nil? || value.to_s.strip.empty?
+
+          order_by = value.to_s.strip.tr(" ", "_").to_sym
+          allowed = Igniter::App::Orchestration::RuntimeEventQuery::ORDERABLE_DIMENSIONS
+          raise ArgumentError, "event_order_by must be one of #{allowed.inspect}" unless allowed.include?(order_by)
+
+          order_by
+        end
+
+        def normalize_credential_order_by(value)
+          return nil if value.nil? || value.to_s.strip.empty?
+
+          order_by = value.to_s.strip.tr(" ", "_").to_sym
+          raise ArgumentError, "credential_order_by must be one of #{CREDENTIAL_ORDERABLE_FIELDS.inspect}" unless CREDENTIAL_ORDERABLE_FIELDS.include?(order_by)
+
+          order_by
+        end
+
+        def normalize_credential_request_order_by(value)
+          return nil if value.nil? || value.to_s.strip.empty?
+
+          order_by = value.to_s.strip.tr(" ", "_").to_sym
+          raise ArgumentError, "credential_request_order_by must be one of #{CREDENTIAL_REQUEST_ORDERABLE_FIELDS.inspect}" unless CREDENTIAL_REQUEST_ORDERABLE_FIELDS.include?(order_by)
+
+          order_by
+        end
+
+        def validate_execution_scope!(graph:, execution_id:)
+          return if present?(graph) && present?(execution_id)
+
+          raise ArgumentError, "graph and execution_id must be provided together"
+        end
+
+        def present?(value)
+          !value.nil? && !value.to_s.empty?
+        end
+
+        def resolved_store(config)
+          store || config&.store || Igniter.execution_store
+        end
+
+        def json_response(status, payload)
+          {
+            status: status,
+            body: JSON.generate(payload),
+            headers: { "Content-Type" => "application/json" }
+          }
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/observability.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "observability/operator_action_handler"
+require_relative "observability/operator_console_handler"
+require_relative "observability/operator_overview_handler"

data/packages/igniter-app/lib/igniter/app/observability_pack.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module ObservabilityPack
+      class << self
+        def install(app_class, path: "/api/operator", limit: 20, store: nil)
+          replace_existing_route!(app_class, "GET", path, handler_class: Observability::OperatorOverviewHandler)
+
+          app_class.route(
+            "GET",
+            path,
+            with: Observability::OperatorOverviewHandler.new(
+              app_class: app_class,
+              limit: limit,
+              store: store
+            )
+          )
+
+          app_class
+        end
+
+        def install_actions(app_class, path: "/api/operator/actions", store: nil)
+          replace_existing_route!(app_class, "POST", path, handler_class: Observability::OperatorActionHandler)
+
+          app_class.route(
+            "POST",
+            path,
+            with: Observability::OperatorActionHandler.new(
+              app_class: app_class,
+              store: store
+            )
+          )
+
+          app_class
+        end
+
+        def install_surface(app_class, path: "/operator", api_path: "/api/operator", action_path: "/api/operator/actions", limit: 20, store: nil, title: nil)
+          install(app_class, path: api_path, limit: limit, store: store)
+          install_actions(app_class, path: action_path, store: store)
+          replace_existing_route!(app_class, "GET", path, handler_class: Observability::OperatorConsoleHandler)
+
+          app_class.route(
+            "GET",
+            path,
+            with: Observability::OperatorConsoleHandler.new(
+              app_class: app_class,
+              api_path: api_path,
+              action_path: action_path,
+              title: title
+            )
+          )
+
+          app_class
+        end
+
+        private
+
+        def replace_existing_route!(app_class, method, path, handler_class:)
+          routes = Array(app_class.instance_variable_get(:@custom_routes)).dup
+          routes.reject! do |route|
+            route[:method] == method &&
+              route[:path] == path &&
+              route[:handler].is_a?(handler_class)
+          end
+          app_class.instance_variable_set(:@custom_routes, routes)
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/operator/dispatcher.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Operator
+      class Dispatcher
+        def call(app_class:, record:, operation: nil, target: nil, value: Igniter::Runtime::Execution::UNDEFINED_RESUME_VALUE, assignee: nil, queue: nil, channel: nil, note: nil, audit: nil)
+          kind = operator_kind_for(record)
+          raise ArgumentError, "operator item #{record[:id].inspect} is not actionable" unless kind
+
+          handler = HandlerRegistry.fetch(kind)
+          kwargs = {
+            app_class: app_class,
+            record: record,
+            operation: operation,
+            target: target,
+            value: value,
+            assignee: assignee,
+            queue: queue,
+            channel: channel,
+            note: note,
+            audit: audit
+          }
+          kwargs.delete(:audit) unless app_class.send(:callable_accepts_keyword?, handler, :audit)
+
+          handler.call(**kwargs)
+        end
+
+        private
+
+        def operator_kind_for(record)
+          kind = record[:record_kind] || record.dig(:lifecycle, :record_kind)
+          return kind.to_sym if kind
+
+          nil
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/operator/handler_registry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Operator
+      class HandlerRegistry
+        class << self
+          def register(kind, handler = nil, &block)
+            resolved_handler = handler || block
+            raise ArgumentError, "operator handler registration requires a callable handler" unless resolved_handler
+
+            registry[normalize_kind(kind)] = resolved_handler
+          end
+
+          def fetch(kind)
+            registry.fetch(normalize_kind(kind))
+          end
+
+          def registered?(kind)
+            registry.key?(normalize_kind(kind))
+          end
+
+          def kinds
+            registry.keys
+          end
+
+          private
+
+          def registry
+            @registry ||= {}
+          end
+
+          def normalize_kind(kind)
+            kind.to_sym
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/operator/handler_result.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Operator
+      class HandlerResult
+        attr_reader :id, :handled_action, :handled_operation, :handled_lifecycle_operation,
+                    :handled_execution_operation, :handled_policy, :handled_lane,
+                    :handled_queue, :handled_channel, :handled_handler_queue,
+                    :handled_audit_source, :handled_actor, :handled_origin,
+                    :handled_actor_channel, :handled_assignee, :note, :status,
+                    :report_status, :payload
+
+        def initialize(id:, handled_action: nil, handled_operation:, handled_lifecycle_operation:,
+                       handled_execution_operation:, handled_policy:, handled_lane: nil,
+                       handled_queue: nil, handled_channel: nil, handled_handler_queue: nil,
+                       handled_audit_source: nil, handled_actor: nil, handled_origin: nil,
+                       handled_actor_channel: nil, handled_assignee: nil, note: nil,
+                       status: nil, report_status: nil, payload: {})
+          @id = id
+          @handled_action = handled_action
+          @handled_operation = handled_operation.to_sym
+          @handled_lifecycle_operation = handled_lifecycle_operation.to_sym
+          @handled_execution_operation = handled_execution_operation.to_sym
+          @handled_policy = handled_policy.to_sym
+          @handled_lane = handled_lane&.to_sym
+          @handled_queue = handled_queue
+          @handled_channel = handled_channel
+          @handled_handler_queue = handled_handler_queue
+          @handled_audit_source = handled_audit_source&.to_sym
+          @handled_actor = handled_actor
+          @handled_origin = handled_origin
+          @handled_actor_channel = handled_actor_channel
+          @handled_assignee = handled_assignee
+          @note = note
+          @status = status&.to_sym
+          @report_status = report_status&.to_sym
+          @payload = payload.dup.freeze
+          freeze
+        end
+
+        def to_h
+          {
+            id: id,
+            handled_action: handled_action,
+            handled_operation: handled_operation,
+            handled_lifecycle_operation: handled_lifecycle_operation,
+            handled_execution_operation: handled_execution_operation,
+            handled_policy: handled_policy,
+            handled_lane: handled_lane,
+            handled_queue: handled_queue,
+            handled_channel: handled_channel,
+            handled_handler_queue: handled_handler_queue,
+            handled_audit_source: handled_audit_source,
+            handled_actor: handled_actor,
+            handled_origin: handled_origin,
+            handled_actor_channel: handled_actor_channel,
+            handled_assignee: handled_assignee,
+            note: note,
+            status: status,
+            report_status: report_status
+          }.merge(payload).compact.freeze
+        end
+      end
+    end
+  end
+end

data/packages/igniter-app/lib/igniter/app/operator/handlers/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Igniter
+  class App
+    module Operator
+      module Handlers
+        class Base
+          private
+
+          def normalize_operation(operation)
+            operation.to_sym
+          end
+
+          def normalize_audit(audit)
+            audit.to_h.each_with_object({}) do |(key, value), memo|
+              memo[key.to_sym] = value
+            end
+          end
+
+          def resolve_operator_action(policy, operation, context: nil)
+            requested_operation = normalize_operation(operation || policy.default_operation)
+            validate_operation!(policy, requested_operation, context: context)
+            resolved_operation =
+              if policy.allowed_operations.include?(requested_operation)
+                requested_operation
+              else
+                policy.canonical_operation_for(requested_operation)
+              end
+
+            {
+              requested_operation: requested_operation,
+              handled_operation: resolved_operation,
+              handled_lifecycle_operation: policy.lifecycle_operation_for(resolved_operation),
+              handled_execution_operation: policy.execution_operation_for(resolved_operation)
+            }.freeze
+          end
+
+          def validate_operation!(policy, applied_operation, context: nil)
+            return if policy.allows_operation?(applied_operation)
+
+            allowed = (policy.allowed_operations + policy.lifecycle_operations).uniq
+            message =
+              if context
+                "operation #{applied_operation.inspect} is not allowed for #{context}; allowed operations: #{allowed.join(', ')}"
+              else
+                "operation #{applied_operation.inspect} is not allowed for operator policy #{policy.name.inspect}; allowed operations: #{allowed.join(', ')}"
+              end
+
+            raise ArgumentError, message
+          end
+
+          def build_result(id:, policy:, action:, action_resolution:, lane:, queue:, channel:, note:, audit:, status:, report_status: nil, assignee: nil, handler_queue: nil, payload: {})
+            HandlerResult.new(
+              id: id,
+              handled_action: action,
+              handled_operation: action_resolution.fetch(:handled_operation),
+              handled_lifecycle_operation: action_resolution.fetch(:handled_lifecycle_operation),
+              handled_execution_operation: action_resolution.fetch(:handled_execution_operation),
+              handled_policy: policy.name,
+              handled_lane: lane,
+              handled_queue: queue,
+              handled_channel: channel,
+              handled_handler_queue: handler_queue,
+              handled_audit_source: audit[:source],
+              handled_actor: audit[:actor],
+              handled_origin: audit[:origin],
+              handled_actor_channel: audit[:actor_channel],
+              handled_assignee: assignee,
+              note: note,
+              status: status,
+              report_status: report_status,
+              payload: payload
+            ).to_h
+          end
+        end
+      end
+    end
+  end
+end