igniter 0.4.5 → 0.5.1

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/runtime/input_validator.rb

@@ -64,7 +64,8 @@ module Igniter
           next if inputs.key?(node.name)
           next unless node.default?
 
-          inputs[node.name] = node.default
+          d = node.default
+          inputs[node.name] = d.respond_to?(:call) ? d.call : d
         end
       end
 
@@ -77,7 +78,10 @@ module Igniter
       end
 
       def missing_value!(input_node)
-        return input_node.default if input_node.default?
+        if input_node.default?
+          d = input_node.default
+          return d.respond_to?(:call) ? d.call : d
+        end
         return nil unless input_node.required?
 
         raise input_error(input_node, "Missing required input: #{input_node.name}")

data/packages/igniter-core/lib/igniter/core/runtime/job_worker.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Runtime
+    class JobWorker
+      def initialize(contract_class, store: Igniter.execution_store)
+        @contract_class = contract_class
+        @store = store
+      end
+
+      def resume(execution_id:, token:, value:)
+        contract = @contract_class.restore_from_store(execution_id, store: @store)
+        contract.execution.resume_by_token(token, value: value)
+        contract
+      end
+
+      def resume_agent_session(execution_id:, session:, node_name: nil, value: Execution::UNDEFINED_RESUME_VALUE)
+        contract = @contract_class.restore_from_store(execution_id, store: @store)
+        contract.execution.resume_agent_session(session, node_name: node_name, value: value)
+        contract
+      end
+
+      def continue_agent_session(execution_id:, session:, payload:, trace: nil, token: nil, waiting_on: nil, request: nil, reply: nil, phase: nil)
+        contract = @contract_class.restore_from_store(execution_id, store: @store)
+        contract.execution.continue_agent_session(
+          session,
+          payload: payload,
+          trace: trace,
+          token: token,
+          waiting_on: waiting_on,
+          request: request,
+          reply: reply,
+          phase: phase
+        )
+        @contract_class.restore_from_store(execution_id, store: @store)
+      end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/runtime/node_state.rb

@@ -4,10 +4,10 @@ module Igniter
   module Runtime
     class NodeState
       attr_reader :node, :status, :value, :error, :version, :value_version,
-                  :resolved_at, :invalidated_by, :dep_snapshot
+                  :resolved_at, :invalidated_by, :dep_snapshot, :details
 
       def initialize(node:, status:, value: nil, error: nil, version: nil, value_version: nil, # rubocop:disable Metrics/ParameterLists
-                     resolved_at: Time.now.utc, invalidated_by: nil, dep_snapshot: nil)
+                     resolved_at: Time.now.utc, invalidated_by: nil, dep_snapshot: nil, details: {})
         @node = node
         @status = status
         @value = value
@@ -17,6 +17,7 @@ module Igniter
         @resolved_at = resolved_at
         @invalidated_by = invalidated_by
         @dep_snapshot = dep_snapshot
+        @details = (details || {}).freeze
       end
 
       def stale?
@@ -47,6 +48,7 @@ module Igniter
           value_version: value_version,
           resolved_at: resolved_at,
           invalidated_by: invalidated_by,
+          details: details,
           value: value,
           error: error
         }

data/packages/igniter-core/lib/igniter/core/runtime/orchestration_overview.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Runtime
+    class OrchestrationOverview
+      attr_reader :execution, :plan
+
+      def initialize(execution:, plan:)
+        @execution = execution
+        @plan = plan.freeze
+      end
+
+      def records
+        @records ||= begin
+          action_index = actions.each_with_object({}) { |action, memo| memo[action[:node].to_sym] = action }
+
+          actions.map do |action|
+            node_name = action[:node].to_sym
+            session = sessions_by_node[node_name]
+            node_entry = node_entries[node_name] || {}
+            state = execution.cache.fetch(node_name)
+            timeline = timeline_for(node_name)
+            orchestration = node_entry[:orchestration] || {}
+            runtime_state = Runtime::OrchestrationRuntimeState.build(
+              node_entry: node_entry,
+              state: state,
+              session: session,
+              timeline: timeline
+            )
+
+            {
+              id: action[:id],
+              node: node_name,
+              action: action[:action],
+              interaction: action[:interaction],
+              reason: action[:reason],
+              guidance: action[:guidance],
+              attention_required: !!action[:attention_required],
+              resumable: !!action[:resumable],
+              status: node_entry[:status] || state&.status,
+              runtime_status: runtime_state.runtime_status,
+              runtime_state: runtime_state.state,
+              runtime_state_class: runtime_state.state_class,
+              runtime_terminal: runtime_state.terminal?,
+              latest_runtime_transition: runtime_state.latest_transition,
+              runtime_transitions: runtime_state.transitions,
+              waiting_on: session&.waiting_on || Array(node_entry[:waiting_on]).first,
+              reply_mode: node_entry[:reply_mode],
+              session_policy: node_entry[:session_policy],
+              tool_loop_policy: node_entry[:tool_loop_policy],
+              finalizer: session&.finalizer || node_entry[:finalizer],
+              routing_mode: session&.routing_mode || node_entry[:routing_mode],
+              interaction_contract: session&.interaction_contract&.to_h || node_entry[:interaction_contract],
+              agent_result_contract: session&.agent_result_contract&.to_h,
+              session_lifecycle_state: session&.lifecycle_state,
+              phase: session&.phase,
+              ownership: session&.ownership,
+              owner_url: session&.owner_url,
+              delivery_route: session&.delivery_route,
+              token: session&.token,
+              turn: session&.turn,
+              interactive: session ? session.interactive? : false,
+              terminal: runtime_state.terminal?,
+              continuable: session ? session.continuable? : false,
+              routed: session ? session.routed? : false,
+              tool_runtime: session&.tool_runtime,
+              allows_continuation: !!orchestration[:allows_continuation],
+              requires_explicit_completion: !!orchestration[:requires_explicit_completion],
+              auto_finalization: orchestration[:auto_finalization],
+              session: session&.to_h,
+              timeline: timeline
+            }.freeze
+          end.freeze
+        end
+      end
+
+      def timeline
+        @timeline ||= actions.flat_map { |action| timeline_for(action[:node]) }.sort_by { |entry| entry[:timestamp].to_s }.freeze
+      end
+
+      def transitions
+        @transitions ||= records.flat_map do |record|
+          Array(record[:runtime_transitions]).map do |transition|
+            {
+              id: record[:id],
+              node: record[:node],
+              action: record[:action],
+              interaction: record[:interaction],
+              reason: record[:reason],
+              runtime_status: record[:runtime_status],
+              runtime_state: record[:runtime_state],
+              runtime_state_class: record[:runtime_state_class]
+            }.merge(transition).freeze
+          end
+        end.sort_by { |entry| entry[:timestamp].to_s }.freeze
+      end
+
+      def transition_query
+        @transition_query ||= Runtime::OrchestrationTransitionQuery.new(transitions)
+      end
+
+      def transition_summary
+        transition_query.summary
+      end
+
+      def summary
+        @summary ||= begin
+          waiting_on = Hash.new(0)
+          records.each do |record|
+            waiting_value = record[:waiting_on]
+            waiting_on[waiting_value] += 1 if waiting_value
+          end
+
+          {
+            total: records.size,
+            attention_required: records.count { |record| record[:attention_required] },
+            resumable: records.count { |record| record[:resumable] },
+            with_session: records.count { |record| !record[:session].nil? },
+            interactive_sessions: records.count { |record| record[:interaction] == :interactive_session },
+            manual_sessions: records.count { |record| record[:interaction] == :manual_session },
+            single_turn_sessions: records.count { |record| record[:interaction] == :single_turn_session },
+            deferred_calls: records.count { |record| record[:interaction] == :deferred_call },
+            by_action: facet(records, :action),
+            by_interaction: facet(records, :interaction),
+            by_runtime_status: facet(records, :runtime_status),
+            by_runtime_state: facet(records, :runtime_state),
+            by_runtime_state_class: facet(records, :runtime_state_class),
+            by_status: facet(records, :status),
+            by_session_lifecycle_state: facet(records, :session_lifecycle_state),
+            by_ownership: facet(records, :ownership),
+            by_phase: facet(records, :phase),
+            by_reply_mode: facet(records, :reply_mode),
+            by_tool_runtime_status: facet(records, :tool_loop_status),
+            by_waiting_on: waiting_on.freeze,
+            terminal_runtime_records: records.count { |record| record[:runtime_terminal] },
+            by_event_type: facet(timeline, :event),
+            recent_events: timeline.last(5).freeze
+          }.freeze
+        end
+      end
+
+      def to_h
+        {
+          summary: summary,
+          records: records,
+          timeline: timeline,
+          transitions: transition_query.to_h
+        }.freeze
+      end
+
+      private
+
+      def actions
+        Array(plan.dig(:orchestration, :actions)).freeze
+      end
+
+      def node_entries
+        @node_entries ||= begin
+          plan.fetch(:nodes, {}).each_with_object({}) do |(node_name, entry), memo|
+            memo[node_name.to_sym] = entry
+          end.freeze
+        end
+      end
+
+      def sessions_by_node
+        @sessions_by_node ||= execution.agent_sessions.each_with_object({}) do |session, memo|
+          memo[session.node_name.to_sym] = session
+        end.freeze
+      end
+
+      def timeline_for(node_name)
+        relevant_events
+          .select { |event| event.node_name == node_name.to_sym }
+          .map { |event| serialize_event(event) }
+          .freeze
+      end
+
+      def relevant_events
+        @relevant_events ||= execution.events.events.select do |event|
+          next false unless event.node_name
+
+          actions.any? { |action| action[:node].to_sym == event.node_name.to_sym }
+        end.freeze
+      end
+
+      def serialize_event(event)
+        payload = event.payload || {}
+
+        {
+          event_id: event.event_id,
+          event: event.type,
+          node: event.node_name,
+          status: event.status,
+          timestamp: event.timestamp,
+          token: payload[:token],
+          turn: payload[:turn],
+          phase: payload[:phase],
+          waiting_on: payload[:waiting_on],
+          payload: payload
+        }.compact.freeze
+      end
+
+      def facet(entries, key)
+        entries.each_with_object(Hash.new(0)) do |entry, memo|
+          value = entry[key]
+          next if value.nil?
+
+          memo[value] += 1
+        end.freeze
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/runtime/orchestration_runtime_state.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Runtime
+    class OrchestrationRuntimeState
+      attr_reader :runtime_status, :state, :state_class, :session_lifecycle_state,
+                  :source_status, :transitions, :latest_transition
+
+      class << self
+        def build(node_entry:, state:, session:, timeline:)
+          new(node_entry: node_entry, state: state, session: session, timeline: timeline)
+        end
+      end
+
+      def initialize(node_entry:, state:, session:, timeline:)
+        @session_lifecycle_state = session&.lifecycle_state
+        @runtime_status = derive_runtime_status(node_entry: node_entry, state: state, session: session)
+        @state = derive_state(node_entry: node_entry, state: state, session: session)
+        @state_class = classify_state(@state)
+        @source_status = (node_entry[:status] || state&.status)&.to_sym
+        @transitions = build_transitions(Array(timeline), session: session).freeze
+        @latest_transition = (@transitions.last || inferred_transition).freeze
+        freeze
+      end
+
+      def terminal?
+        latest_transition[:terminal]
+      end
+
+      def to_h
+        {
+          runtime_status: runtime_status,
+          state: state,
+          state_class: state_class,
+          session_lifecycle_state: session_lifecycle_state,
+          source_status: source_status,
+          terminal: terminal?,
+          transitions: transitions,
+          latest_transition: latest_transition
+        }.freeze
+      end
+
+      private
+
+      def derive_runtime_status(node_entry:, state:, session:)
+        return :pending_session if session
+        return :completed if state&.succeeded?
+        return :failed if state&.failed?
+        return :running if state&.running?
+        return :pending if state&.pending?
+        return :ready if node_entry[:ready]
+        return :blocked if node_entry[:blocked]
+
+        (node_entry[:status] || state&.status || :unknown).to_sym
+      end
+
+      def derive_state(node_entry:, state:, session:)
+        return session_state(session) if session
+        return :completed if state&.succeeded?
+        return :failed if state&.failed?
+        return :running if state&.running?
+        return :pending_resolution if state&.pending?
+        return :ready if node_entry[:ready]
+        return :blocked if node_entry[:blocked]
+
+        normalize_state_name(node_entry[:status] || state&.status || :unknown)
+      end
+
+      def session_state(session)
+        case session&.lifecycle_state
+        when :waiting
+          :awaiting_reply
+        when :streaming
+          :streaming
+        when :completed
+          :completed
+        else
+          :pending_session
+        end
+      end
+
+      def classify_state(state_name)
+        case state_name
+        when :completed, :failed
+          :terminal
+        when :awaiting_reply, :streaming, :pending_session
+          :session
+        when :running
+          :active
+        when :pending, :pending_resolution
+          :pending
+        when :ready
+          :ready
+        when :blocked
+          :blocked
+        else
+          :unknown
+        end
+      end
+
+      def build_transitions(timeline, session:)
+        timeline.filter_map do |entry|
+          transition = transition_for_event(entry, session: session)
+          transition&.freeze
+        end
+      end
+
+      def transition_for_event(entry, session:)
+        payload = entry[:payload] || {}
+        transition_state =
+          case entry[:event]&.to_sym
+          when :node_started
+            :running
+          when :node_pending
+            pending_state_from_payload(payload, session: session)
+          when :agent_session_continued
+            session_state_from_payload(payload)
+          when :agent_session_completed, :node_resumed, :node_succeeded, :node_skipped,
+               :node_content_cache_hit, :node_ttl_cache_hit, :node_coalesced, :node_backdated
+            :completed
+          when :node_failed
+            :failed
+          else
+            nil
+          end
+        return nil unless transition_state
+
+        {
+          event: entry[:event]&.to_sym,
+          status: entry[:status]&.to_sym,
+          state: transition_state,
+          state_class: classify_state(transition_state),
+          terminal: %i[completed failed].include?(transition_state),
+          timestamp: entry[:timestamp],
+          turn: payload[:turn],
+          phase: payload[:phase]&.to_sym,
+          waiting_on: (payload[:waiting_on] || payload.dig(:agent_session, :waiting_on))&.to_sym,
+          source_status: entry[:status]&.to_sym
+        }.compact
+      end
+
+      def pending_state_from_payload(payload, session:)
+        session_state_from_payload(payload) || session_state(session) || :pending_resolution
+      end
+
+      def session_state_from_payload(payload)
+        raw_session =
+          payload[:agent_session] ||
+          payload["agent_session"] ||
+          payload.dig(:payload, :agent_session) ||
+          payload.dig("payload", "agent_session")
+        return nil unless raw_session
+
+        session = Runtime::AgentSession.from_h(raw_session)
+        session_state(session)
+      rescue StandardError
+        nil
+      end
+
+      def inferred_transition
+        {
+          event: :state_inferred,
+          status: source_status,
+          state: state,
+          state_class: state_class,
+          terminal: %i[completed failed].include?(state),
+          source_status: source_status
+        }.compact
+      end
+
+      def normalize_state_name(value)
+        value.to_sym
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/runtime/orchestration_transition_query.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Runtime
+    class OrchestrationTransitionQuery
+      include Enumerable
+
+      FILTERABLE_DIMENSIONS = %i[
+        id node action interaction state state_class event status terminal
+        phase waiting_on source_status
+      ].freeze
+      ORDERABLE_DIMENSIONS = %i[
+        id node action interaction state state_class event status terminal
+        phase waiting_on source_status timestamp turn
+      ].freeze
+
+      def initialize(transitions)
+        @transitions = Array(transitions).map(&:dup).freeze
+        @filters = [].freeze
+        @orderings = [].freeze
+        @limit_count = nil
+        freeze
+      end
+
+      def id(*ids)
+        normalized = ids.map(&:to_s)
+        add_filter { |entry| normalized.include?(entry[:id].to_s) }
+      end
+
+      def node(*nodes)
+        normalized = nodes.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:node]) }
+      end
+
+      def action(*actions)
+        normalized = actions.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:action]) }
+      end
+
+      def interaction(*interactions)
+        normalized = interactions.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:interaction]) }
+      end
+
+      def state(*states)
+        normalized = states.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:state]) }
+      end
+
+      def state_class(*classes)
+        normalized = classes.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:state_class]) }
+      end
+
+      def event(*events)
+        normalized = events.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:event]) }
+      end
+
+      def status(*statuses)
+        normalized = statuses.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:status]) }
+      end
+
+      def phase(*phases)
+        normalized = phases.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:phase]) }
+      end
+
+      def waiting_on(*nodes)
+        normalized = nodes.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:waiting_on]) }
+      end
+
+      def source_status(*statuses)
+        normalized = statuses.map(&:to_sym)
+        add_filter { |entry| normalized.include?(entry[:source_status]) }
+      end
+
+      def terminal(value = true)
+        expected = !!value
+        add_filter { |entry| entry[:terminal] == expected }
+      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)
+        unless FILTERABLE_DIMENSIONS.include?(dimension)
+          raise ArgumentError, "Unknown facet dimension: #{dimension.inspect}. Use one of #{FILTERABLE_DIMENSIONS.inspect}"
+        end
+
+        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] },
+          by_node: facet(:node),
+          by_action: facet(:action),
+          by_interaction: facet(:interaction),
+          by_state: facet(:state),
+          by_state_class: facet(:state_class),
+          by_event: facet(:event),
+          by_status: facet(:status),
+          latest_transition: entries.last&.dup,
+          latest_per_node: latest_per_node(entries)
+        }.freeze
+      end
+
+      def to_h(limit: 20)
+        {
+          summary: summary,
+          transitions: order_by(:timestamp).limit(limit).to_a,
+          recent_transitions: order_by(:timestamp).to_a.last(limit)
+        }.freeze
+      end
+
+      def each(&block)
+        to_a.each(&block)
+      end
+
+      def to_a
+        entries = @transitions.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(:@transitions, @transitions)
+          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