igniter 0.5.0 → 0.5.1

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/extensions/introspection/graph_formatter.rb

@@ -36,8 +36,26 @@ module Igniter
             if node.kind == :composition
               line += " contract=#{node.contract_class.name || 'AnonymousContract'}"
             end
+            if node.kind == :agent
+              interaction = node.interaction_contract
+              line += " via=#{node.agent_name.inspect}"
+              line += " message=#{node.message_name.inspect}"
+              line += " timeout=#{node.timeout}"
+              line += " mode=#{interaction.mode}"
+              line += " routing=#{interaction.routing_mode}"
+              line += " node=#{interaction.node_url.inspect}" if interaction.routing_mode == :static
+              line += " capability=#{interaction.capability.inspect}" if interaction.capability
+              line += " query=#{interaction.capability_query.inspect}" if interaction.capability_query
+              line += " pinned_to=#{interaction.pinned_to.inspect}" if interaction.pinned_to
+              line += " reply=#{interaction.reply_mode}"
+              line += " finalizer=#{interaction.finalizer.inspect}" if interaction.finalizer
+              line += " tool_loop_policy=#{interaction.tool_loop_policy.inspect}" if interaction.tool_loop_policy
+              line += " session_policy=#{interaction.session_policy.inspect}" if interaction.session_policy
+            end
             if node.kind == :branch
-              cases = node.cases.map { |entry| "#{entry[:match].inspect}:#{entry[:contract].name || 'AnonymousContract'}" }
+              cases = node.cases.map do |entry|
+                "#{format_branch_case(entry)}:#{entry[:contract].name || 'AnonymousContract'}"
+              end
               line += " selector=#{node.selector_dependency}"
               line += " depends_on=#{node.context_dependencies.join(',')}" if node.context_dependencies.any?
               line += " cases=#{cases.join('|')}"
@@ -97,6 +115,19 @@ module Igniter
 
           "#{node.kind}: #{node.path}\\n#{node.callable_name}"
         end
+
+        def format_branch_case(entry)
+          case entry[:matcher]
+          when :eq
+            entry[:value].inspect
+          when :in
+            "in=#{entry[:value].inspect}"
+          when :matches
+            "matches=#{entry[:value].inspect}"
+          else
+            "#{entry[:matcher]}=#{entry[:value].inspect}"
+          end
+        end
       end
     end
   end

data/packages/igniter-core/lib/igniter/core/extensions/introspection/plan_formatter.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Introspection
+      class PlanFormatter
+        def self.to_text(execution, output_names = nil)
+          new(execution, output_names).to_text
+        end
+
+        def initialize(execution, output_names = nil)
+          @execution = execution
+          @plan = execution.plan(output_names)
+        end
+
+        def to_text
+          lines = []
+          lines << "Plan #{@execution.compiled_graph.name}"
+          lines << "Targets: #{format_list(@plan[:targets])}"
+          lines << "Ready: #{format_list(@plan[:ready])}"
+          lines << "Blocked: #{format_list(@plan[:blocked])}"
+          if @plan[:agent_profiles] && @plan[:agent_profiles][:total].positive?
+            lines << "Agents: total=#{@plan[:agent_profiles][:total]}, interactive=#{@plan[:agent_profiles][:interactive]}, manual=#{@plan[:agent_profiles][:manual]}, single_turn=#{@plan[:agent_profiles][:single_turn]}, streaming=#{@plan[:agent_profiles][:streaming]}, deferred=#{@plan[:agent_profiles][:deferred]}"
+          end
+          if @plan[:orchestration] && @plan[:orchestration][:total].positive?
+            lines << "Orchestration: attention_required=#{@plan[:orchestration][:attention_required]}, resumable=#{@plan[:orchestration][:resumable]}, interactive_sessions=#{@plan[:orchestration][:interactive_sessions]}, manual_sessions=#{@plan[:orchestration][:manual_sessions]}, single_turn_sessions=#{@plan[:orchestration][:single_turn_sessions]}, deferred_calls=#{@plan[:orchestration][:deferred_calls]}, single_reply_calls=#{@plan[:orchestration][:single_reply_calls]}, delivery_only=#{@plan[:orchestration][:delivery_only]}"
+            if @plan[:orchestration][:attention_nodes].any?
+              lines << "Attention Nodes: #{format_list(@plan[:orchestration][:attention_nodes])}"
+            end
+            if @plan[:orchestration][:actions].any?
+              lines << "Orchestration Actions: #{@plan[:orchestration][:actions].map { |action| "#{action[:node]}(#{action[:action]})" }.join(', ')}"
+            end
+          end
+          lines << "Nodes:"
+
+          @plan[:nodes].each_value do |entry|
+            lines << format_node(entry)
+          end
+
+          lines.join("\n")
+        end
+
+        private
+
+        def format_node(entry)
+          line = "- #{entry[:kind]} #{entry[:path]} status=#{entry[:status]}"
+          line += " ready=true" if entry[:ready]
+          line += " blocked=true" if entry[:blocked]
+          line += " waiting_on=#{format_list(entry[:waiting_on])}" if entry[:waiting_on].any?
+          if entry[:kind] == :agent
+            line += " via=#{entry[:via].inspect}"
+            line += " message=#{entry[:message].inspect}"
+            line += " mode=#{entry[:mode]}"
+            line += " reply=#{entry[:reply_mode]}"
+            line += " session_policy=#{entry[:session_policy]}" if entry[:session_policy]
+            line += " tool_loop_policy=#{entry[:tool_loop_policy]}" if entry[:tool_loop_policy]
+            line += " finalizer=#{entry[:finalizer].inspect}" if entry[:finalizer]
+            if entry[:orchestration]
+              line += " orchestration=#{entry[:orchestration][:interaction]}"
+              line += " guidance=#{entry[:orchestration][:guidance].inspect}"
+              line += " attention_required=true" if entry[:orchestration][:attention_required]
+              line += " resumable=true" if entry[:orchestration][:resumable]
+              line += " allows_continuation=true" if entry[:orchestration][:allows_continuation]
+              line += " requires_explicit_completion=true" if entry[:orchestration][:requires_explicit_completion]
+              line += " auto_finalization=#{entry[:orchestration][:auto_finalization]}"
+            end
+          end
+
+          dependency_summary = entry[:dependencies].map do |dependency|
+            "#{dependency[:name]}(#{dependency[:status]})"
+          end
+          line += " deps=#{dependency_summary.join(',')}" if dependency_summary.any?
+          line
+        end
+
+        def format_list(values)
+          array = Array(values)
+          return "none" if array.empty?
+
+          array.join(",")
+        end
+      end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/extensions/introspection/runtime_formatter.rb

@@ -73,6 +73,7 @@ module Igniter
             status: state.status,
             version: state.version,
             invalidated_by: invalidation_details(state),
+            details: state.details,
             value: serialize_value(state.value),
             error: state.error&.message
           }
@@ -91,6 +92,31 @@ module Igniter
 
         def serialize_value(value)
           case value
+          when Igniter::Runtime::StreamResult
+            {
+              type: :stream,
+              token: value.token,
+              payload: value.payload,
+              source_node: value.source_node,
+              waiting_on: value.waiting_on,
+              phase: value.phase,
+              events: value.events,
+              event_count: value.events.size,
+              status_count: value.status_events.size,
+              tool_call_count: value.tool_calls.size,
+              tool_result_count: value.tool_results.size,
+              tool_interaction_count: value.tool_interactions.size,
+              pending_tool_interaction_count: value.pending_tool_interactions.size,
+              completed_tool_interaction_count: value.completed_tool_interactions.size,
+              orphan_tool_interaction_count: value.orphan_tool_interactions.size,
+              tool_loop_status: value.tool_loop_status,
+              tool_loop_complete: value.tool_loop_complete?,
+              tool_loop_summary: value.tool_loop_summary,
+              tool_runtime: value.tool_runtime,
+              artifact_count: value.artifacts.size,
+              chunks: value.chunks,
+              chunk_count: value.chunks.size
+            }
           when Igniter::Runtime::DeferredResult
             {
               type: :deferred,

data/packages/igniter-core/lib/igniter/core/extensions/invariants.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../contract"
+require_relative "../errors"
+require_relative "../invariant"
+
+module Igniter
+  module Extensions
+    # Patches Igniter::Contract with:
+    #   - Class method: invariant(name) { |output:, **| condition }
+    #   - Instance method: check_invariants -> Array<InvariantViolation>
+    #   - Automatic post-execution check in resolve_all (raises InvariantError)
+    module Invariants
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.prepend(InstanceMethods)
+      end
+
+      module ClassMethods
+        def invariant(name, &block)
+          @_invariants ||= {}
+          @_invariants[name.to_sym] = Igniter::Invariant.new(name, &block)
+        end
+
+        def invariants
+          @_invariants || {}
+        end
+      end
+
+      module InstanceMethods
+        def resolve_all(...)
+          result = super
+          validate_invariants! unless Thread.current[:igniter_skip_invariants]
+          result
+        end
+
+        def check_invariants
+          return [] if self.class.invariants.empty?
+
+          resolved = collect_output_values
+          self.class.invariants.values.filter_map { |inv| inv.check(resolved) }
+        end
+
+        private
+
+        def validate_invariants!
+          violations = check_invariants
+          return if violations.empty?
+
+          names = violations.map { |v| ":#{v.name}" }.join(", ")
+          raise Igniter::InvariantError.new(
+            "#{violations.size} invariant(s) violated: #{names}",
+            violations: violations,
+            context: { contract: self.class.name }
+          )
+        end
+
+        def collect_output_values
+          cache = execution.cache
+          execution.compiled_graph.outputs.each_with_object({}) do |output_node, acc|
+            state = cache.fetch(output_node.source_root)
+            acc[output_node.name] = state.value if state&.succeeded?
+          end
+        end
+      end
+    end
+  end
+end
+
+Igniter::Contract.include(Igniter::Extensions::Invariants)

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

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require "igniter"
-require "igniter/incremental/result"
-require "igniter/incremental/tracker"
-require "igniter/incremental/formatter"
+require_relative "errors"
+require_relative "incremental/result"
+require_relative "incremental/tracker"
+require_relative "incremental/formatter"
 
 module Igniter
   # Incremental computation for Igniter contracts.

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/memory/memorable.rb

@@ -3,7 +3,7 @@
 module Igniter
   module Memory
     # Mixin that adds episodic memory capabilities to Igniter::Agent and
-    # Igniter::LLM::Executor subclasses (or any class that includes it).
+    # Igniter::AI::Executor subclasses (or any class that includes it).
     #
     # Including +Memorable+ adds:
     # * A class-level +enable_memory+ DSL method for opt-in activation

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/memory/stores/sqlite.rb

@@ -6,8 +6,9 @@ module Igniter
       # SQLite-backed persistent Store implementation.
       #
       # Uses SQLite3 with FTS5 for fast full-text search on episode content.
-      # Requires the +sqlite3+ gem (soft dependency — not declared in the gemspec).
-      # Raises +Igniter::Memory::ConfigurationError+ if the gem is not available.
+      # Igniter ships with the +sqlite3+ gem as a standard dependency.
+      # Raises +Igniter::Memory::ConfigurationError+ if the runtime environment
+      # is incomplete and the gem cannot be loaded.
       #
       # @example In-memory SQLite (for tests)
       #   store = Igniter::Memory::Stores::SQLite.new(path: ":memory:")
@@ -20,7 +21,8 @@ module Igniter
           require "sqlite3"
         rescue LoadError
           raise ConfigurationError,
-                "SQLite store requires the 'sqlite3' gem. Add it to your Gemfile: gem 'sqlite3'"
+                "`igniter` now ships with a required `sqlite3` dependency. " \
+                "If it is missing in this environment, run bundle install or reinstall the gem."
         else
           @mutex = Mutex.new
           @db    = ::SQLite3::Database.new(path)

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

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-require "igniter/errors"
-require "igniter/memory/episode"
-require "igniter/memory/fact"
-require "igniter/memory/reflection_record"
-require "igniter/memory/store"
-require "igniter/memory/stores/in_memory"
-require "igniter/memory/stores/sqlite"
-require "igniter/memory/reflection_cycle"
-require "igniter/memory/agent_memory"
-require "igniter/memory/memorable"
+require_relative "errors"
+require_relative "memory/episode"
+require_relative "memory/fact"
+require_relative "memory/reflection_record"
+require_relative "memory/store"
+require_relative "memory/stores/in_memory"
+require_relative "memory/stores/sqlite"
+require_relative "memory/reflection_cycle"
+require_relative "memory/agent_memory"
+require_relative "memory/memorable"
 
 module Igniter
   # Pluggable episodic memory system for Agents and Skills.
@@ -19,7 +19,7 @@ module Igniter
   #
   # == Quick start
   #
-  #   require "igniter/memory"
+  #   require "igniter/core/memory"
   #
   #   class MyAgent < Igniter::Agent
   #     include Igniter::Memory::Memorable

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/metrics/prometheus_exporter.rb

@@ -17,7 +17,7 @@ module Igniter
         "igniter_executions_total" =>
           "Total contract executions completed",
         "igniter_http_requests_total" =>
-          "Total HTTP requests received by igniter-server"
+          "Total HTTP requests received by igniter-stack"
       }.freeze
 
       HISTOGRAM_META = {

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

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require "igniter"
-require "igniter/metrics/snapshot"
-require "igniter/metrics/collector"
-require "igniter/metrics/prometheus_exporter"
+require_relative "errors"
+require_relative "metrics/snapshot"
+require_relative "metrics/collector"
+require_relative "metrics/prometheus_exporter"
 
 module Igniter
-  # Metrics collection for Igniter contracts and igniter-server.
+  # Metrics collection for Igniter contracts and igniter-stack.
   #
   # The Collector subscribes to an Igniter::Events::Bus and maintains
   # in-memory counters and histograms with zero external dependencies.
   #
   # Prometheus text format is exported via PrometheusExporter — usable
-  # directly in the /v1/metrics endpoint of igniter-server.
+  # directly in the /v1/metrics endpoint of igniter-stack.
   #
   # Usage (standalone):
-  #   require "igniter/metrics"
+  #   require "igniter/core/metrics"
   #
   #   collector = Igniter::Metrics::Collector.new
   #   contract.execution.events.subscribe(collector)
@@ -26,7 +26,7 @@ module Igniter
   #   )
   #   puts exporter.export
   #
-  # Usage (igniter-server — automatic when metrics_collector is set):
+  # Usage (igniter-stack — automatic when metrics_collector is set):
   #   Igniter::Server.configure do |c|
   #     c.metrics_collector = Igniter::Metrics::Collector.new
   #   end

data/packages/igniter-core/lib/igniter/core/model/agent_interaction_contract.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    class AgentInteractionContract
+      SYMBOL_LIST_KEYS = RemoteNode::SYMBOL_LIST_KEYS
+      SYMBOL_SCALAR_KEYS = RemoteNode::SYMBOL_SCALAR_KEYS
+
+      MODES = %i[call cast].freeze
+      REPLY_MODES = %i[single deferred stream none].freeze
+      TOOL_LOOP_POLICIES = %i[ignore resolved complete].freeze
+      SESSION_POLICIES = %i[interactive single_turn manual].freeze
+      ROUTING_MODES = %i[local static capability pinned].freeze
+
+      attr_reader :mode, :reply_mode, :finalizer, :tool_loop_policy, :session_policy,
+                  :node_url, :capability, :capability_query, :pinned_to
+
+      def initialize(mode: :call, reply_mode: nil, finalizer: nil, tool_loop_policy: nil, session_policy: nil,
+                     node_url: nil, capability: nil, capability_query: nil, pinned_to: nil)
+        @mode = normalize_mode(mode)
+        @reply_mode = normalize_reply_mode(reply_mode || default_reply_mode(@mode))
+        @finalizer = normalize_finalizer(finalizer || default_finalizer(@reply_mode))
+        @tool_loop_policy = normalize_tool_loop_policy(tool_loop_policy || default_tool_loop_policy(@reply_mode))
+        @session_policy = normalize_session_policy(session_policy || default_session_policy(@reply_mode))
+        @node_url = node_url&.to_s
+        @capability = capability&.to_sym
+        @capability_query = normalize_query(capability_query)
+        @pinned_to = pinned_to&.to_s
+        freeze
+      end
+
+      def routing_mode
+        return :pinned if pinned?
+        return :capability if capability_routed?
+        return :static if static?
+
+        :local
+      end
+
+      def call?
+        mode == :call
+      end
+
+      def cast?
+        mode == :cast
+      end
+
+      def streaming?
+        reply_mode == :stream
+      end
+
+      def static?
+        !node_url.nil? && !node_url.empty?
+      end
+
+      def capability_routed?
+        !capability.nil? || !capability_query.nil?
+      end
+
+      def pinned?
+        !pinned_to.nil? && !pinned_to.empty?
+      end
+
+      def to_h
+        payload = {
+          mode: mode,
+          routing_mode: routing_mode,
+          reply: reply_mode,
+          finalizer: serialized_finalizer,
+          tool_loop_policy: tool_loop_policy,
+          session_policy: session_policy
+        }
+        payload[:node] = node_url if routing_mode == :static
+        payload[:capability] = capability if capability
+        payload[:query] = capability_query if capability_query
+        payload[:pinned_to] = pinned_to if pinned_to
+        payload.freeze
+      end
+
+      private
+
+      def normalize_mode(mode)
+        return mode.to_sym if mode.is_a?(String) || mode.is_a?(Symbol)
+
+        mode
+      end
+
+      def normalize_reply_mode(reply_mode)
+        return reply_mode.to_sym if reply_mode.is_a?(String) || reply_mode.is_a?(Symbol)
+
+        reply_mode
+      end
+
+      def default_reply_mode(mode)
+        mode == :cast ? :none : :deferred
+      end
+
+      def normalize_finalizer(finalizer)
+        return finalizer.to_sym if finalizer.is_a?(String) || finalizer.is_a?(Symbol)
+
+        finalizer
+      end
+
+      def default_finalizer(reply_mode)
+        reply_mode == :stream ? :join : nil
+      end
+
+      def normalize_tool_loop_policy(tool_loop_policy)
+        return tool_loop_policy.to_sym if tool_loop_policy.is_a?(String) || tool_loop_policy.is_a?(Symbol)
+
+        tool_loop_policy
+      end
+
+      def default_tool_loop_policy(reply_mode)
+        reply_mode == :stream ? :complete : nil
+      end
+
+      def normalize_session_policy(session_policy)
+        return session_policy.to_sym if session_policy.is_a?(String) || session_policy.is_a?(Symbol)
+
+        session_policy
+      end
+
+      def default_session_policy(reply_mode)
+        reply_mode == :stream ? :interactive : nil
+      end
+
+      def normalize_query(query)
+        case query
+        when nil
+          nil
+        when Symbol, String
+          { all_of: [query.to_sym] }.freeze
+        when Array
+          { all_of: query.map(&:to_sym).freeze }.freeze
+        when Hash
+          normalize_query_hash(query).freeze
+        else
+          query
+        end
+      end
+
+      def normalize_query_hash(hash)
+        hash.each_with_object({}) do |(key, value), memo|
+          normalized_key = key.to_sym
+          memo[normalized_key] = normalize_query_value(normalized_key, value)
+        end
+      end
+
+      def normalize_query_value(key, value)
+        if SYMBOL_LIST_KEYS.include?(key)
+          Array(value).map { |item| item.is_a?(String) || item.is_a?(Symbol) ? item.to_sym : item }.freeze
+        elsif SYMBOL_SCALAR_KEYS.include?(key) && (value.is_a?(String) || value.is_a?(Symbol))
+          value.to_sym
+        elsif value.is_a?(Hash)
+          normalize_query_hash(value).freeze
+        elsif value.is_a?(Array)
+          value.map { |item| item.is_a?(Hash) ? normalize_query_hash(item).freeze : item }.freeze
+        else
+          value
+        end
+      end
+
+      def serialized_finalizer
+        return nil if finalizer.nil?
+        return finalizer if finalizer.is_a?(Symbol)
+
+        :proc
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/model/agent_node.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Model
+    # Represents a graph node that delegates work to a long-lived agent.
+    #
+    # The node itself is part of the contract graph. Delivery and lookup are
+    # delegated to a runtime adapter so core stays independent from any specific
+    # actor runtime implementation or registry strategy.
+    class AgentNode < Node
+      attr_reader :agent_name, :message_name, :input_mapping, :timeout, :mode,
+                  :interaction_contract
+
+      def initialize(id:, name:, agent_name:, message_name:, input_mapping:, timeout: 5, mode: :call, reply_mode: nil, finalizer: nil, tool_loop_policy: nil, session_policy: nil, node_url: nil, capability: nil, capability_query: nil, pinned_to: nil, path: nil, metadata: {}) # rubocop:disable Metrics/ParameterLists
+        super(
+          id: id,
+          kind: :agent,
+          name: name,
+          path: path || name.to_s,
+          dependencies: input_mapping.values.map(&:to_sym),
+          metadata: metadata
+        )
+        @agent_name = normalize_agent_name(agent_name)
+        @message_name = message_name.to_sym
+        @input_mapping = input_mapping.transform_keys(&:to_sym).transform_values(&:to_sym).freeze
+        @timeout = Float(timeout)
+        @interaction_contract = AgentInteractionContract.new(
+          mode: mode,
+          reply_mode: reply_mode,
+          finalizer: finalizer,
+          tool_loop_policy: tool_loop_policy,
+          session_policy: session_policy,
+          node_url: node_url,
+          capability: capability,
+          capability_query: capability_query,
+          pinned_to: pinned_to
+        )
+        @mode = @interaction_contract.mode
+      end
+
+      def routing_mode
+        interaction_contract.routing_mode
+      end
+
+      def reply_mode
+        interaction_contract.reply_mode
+      end
+
+      def finalizer
+        interaction_contract.finalizer
+      end
+
+      def tool_loop_policy
+        interaction_contract.tool_loop_policy
+      end
+
+      def session_policy
+        interaction_contract.session_policy
+      end
+
+      def node_url
+        interaction_contract.node_url
+      end
+
+      def capability
+        interaction_contract.capability
+      end
+
+      def capability_query
+        interaction_contract.capability_query
+      end
+
+      def pinned_to
+        interaction_contract.pinned_to
+      end
+
+      private
+
+      def normalize_agent_name(agent_name)
+        return agent_name.to_sym if agent_name.is_a?(String) || agent_name.is_a?(Symbol)
+
+        agent_name
+      end
+    end
+  end
+end