igniter 0.4.5 → 0.5.1

data/packages/igniter-cluster/lib/igniter/cluster/replication/expansion_plan.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Replication
+    # Immutable value object returned by ExpansionPlanner.
+    #
+    # Carries an ordered list of actions the replication system should execute
+    # and a human-readable rationale explaining why each action was chosen.
+    #
+    # Recognised action hashes:
+    #   { action: :replicate_capabilities, query: { all_of: [:local_llm] }, host: "10.0.0.2" }
+    #   { action: :retire_node,            node_id: "abc",                   host: "10.0.0.1" }
+    #   { action: :no_op }
+    class ExpansionPlan
+      attr_reader :actions, :rationale
+
+      # @param actions   [Array<Hash>]
+      # @param rationale [String, nil]
+      def initialize(actions:, rationale: nil)
+        @actions   = Array(actions).freeze
+        @rationale = rationale
+        freeze
+      end
+
+      # True when there is nothing to do.
+      #
+      # @return [Boolean]
+      def no_op?
+        @actions.all? { |a| a[:action] == :no_op }
+      end
+
+      # @return [Hash]
+      def to_h
+        { actions: @actions, rationale: @rationale }
+      end
+    end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/replication/expansion_planner.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Replication
+    # Analyses network topology + episodic memory to produce an ExpansionPlan.
+    #
+    # Two modes of operation:
+    # * **Rule-based** (default) — applies fixed heuristics, no LLM required.
+    # * **LLM-assisted** — delegates to an LLM executor for intent-rich reasoning.
+    #
+    # Rule-based heuristics (applied in order):
+    # 1. Retire nodes marked unhealthy in the topology.
+    # 2. Spawn a new node for each required capability query absent from the topology.
+    # 3. Annotate the rationale when recent replication failures exceed the threshold.
+    # 4. Honour :scale_signal episodes (content: "scale_out:<capability>[+<capability>]").
+    #
+    # LLM mode receives topology snapshot + recent episodes and expects the
+    # executor to return { actions: [...], rationale: "..." }.
+    #
+    # @example Rule-based
+    #   topology = NetworkTopology.new
+    #   topology.register(node_id: "x", host: "10.0.0.1", capabilities: [:local_llm])
+    #
+    #   planner = ExpansionPlanner.new(
+    #     topology:              topology,
+    #     required_capabilities: [[:local_llm], %i[container_runtime local_llm]],
+    #     host_pool:             ["10.0.0.2"]
+    #   )
+    #   plan = planner.plan
+    #   # plan.actions => [{ action: :replicate_capabilities, query: { all_of: [:container_runtime, :local_llm] }, host: "10.0.0.2" }]
+    class ExpansionPlanner
+      DEFAULT_FAILURE_THRESHOLD = 3
+
+      # @param topology          [NetworkTopology]     current node topology
+      # @param memory            [AgentMemory, nil]    episodic memory (optional)
+      # @param required_capabilities [Array<CapabilityQuery, Array<Symbol>, Hash, Symbol>]
+      #   capability slices that must always be present
+      # @param failure_threshold [Integer]             replication failures before warning
+      # @param host_pool         [Array<String>]       candidate hosts for new nodes
+      # @param llm               [#call, nil]          optional LLM executor
+      def initialize(topology:, memory: nil, required_capabilities: [],
+                     failure_threshold: DEFAULT_FAILURE_THRESHOLD,
+                     host_pool: [], llm: nil)
+        @topology              = topology
+        @memory                = memory
+        @required_capabilities = Array(required_capabilities).map { |query| CapabilityQuery.normalize(query) }
+        @failure_threshold     = failure_threshold
+        @host_pool             = host_pool.dup
+        @llm                   = llm
+      end
+
+      # Produce an ExpansionPlan.
+      #
+      # @return [ExpansionPlan]
+      def plan
+        @llm ? smart_plan : rule_based_plan
+      end
+
+      private
+
+      def rule_based_plan
+        actions   = []
+        rationale = []
+
+        retire_unhealthy(actions, rationale)
+        ensure_required_capabilities(actions, rationale)
+        check_failure_signal(rationale)
+        apply_scale_signals(actions, rationale)
+
+        actions << { action: :no_op } if actions.empty?
+        ExpansionPlan.new(actions: actions, rationale: rationale.join("; "))
+      end
+
+      def retire_unhealthy(actions, rationale)
+        @topology.nodes.reject(&:healthy).each do |node|
+          actions   << { action: :retire_node, node_id: node.node_id, host: node.host }
+          rationale << "node #{node.node_id} (#{node.host}) is unhealthy"
+        end
+      end
+
+      def ensure_required_capabilities(actions, rationale)
+        @required_capabilities.each do |query|
+          next unless @topology.needs_capability_query?(query)
+
+          host = next_available_host
+          if host
+            actions   << { action: :replicate_capabilities, query: query.to_h, host: host }
+            rationale << "capability query #{query.label.inspect} absent; targeting #{host}"
+          else
+            rationale << "capability query #{query.label.inspect} absent but no available host in pool"
+          end
+        end
+      end
+
+      def check_failure_signal(rationale)
+        return unless @memory
+
+        failures = @memory.recent(last: 20, type: :replication_event)
+                          .count { |e| e.outcome == "failure" }
+        if failures >= @failure_threshold
+          rationale << "#{failures} recent replication failures — check SSH credentials"
+        end
+      end
+
+      def apply_scale_signals(actions, rationale)
+        return unless @memory
+
+        @memory.recent(last: 10, type: :scale_signal).each do |ep|
+          m = ep.content.to_s.match(/\Ascale_out:([@\w+,-]+)\z/)
+          next unless m
+
+          query = parse_scale_query(m[1])
+          host = next_available_host
+          if host
+            actions   << { action: :replicate_capabilities, query: query.to_h, host: host }
+            rationale << "scale_signal requests #{query.label.inspect} at #{host}"
+          end
+        end
+      end
+
+      def smart_plan
+        episodes = @memory&.recent(last: 50) || []
+        result   = @llm.call(
+          topology:       @topology.nodes.map { |n|
+                            { node_id: n.node_id, host: n.host,
+                              capabilities: n.capabilities, tags: n.tags, healthy: n.healthy }
+                          },
+          episodes:       episodes.map { |e|
+                            { type: e.type, content: e.content, outcome: e.outcome }
+                          },
+          required_capabilities: @required_capabilities.map(&:to_h),
+          host_pool:      @host_pool
+        )
+        ExpansionPlan.new(actions: Array(result[:actions]), rationale: result[:rationale])
+      end
+
+      def next_available_host
+        used = @topology.nodes.map(&:host).to_set
+        @host_pool.find { |h| !used.include?(h) }
+      end
+
+      def parse_scale_query(signature)
+        body, tag_part = signature.split("@", 2)
+
+        CapabilityQuery.new(
+          all_of: body.to_s.split("+").reject(&:empty?),
+          tags:   tag_part.to_s.split("+").reject(&:empty?)
+        )
+      end
+    end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/replication/manifest.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Igniter
+  module Cluster
+    module Replication
+    # Self-description of a running Igniter instance, used during replication.
+    #
+    # Call Manifest.current to capture the current process's metadata.
+    class Manifest
+      attr_reader :gem_version, :ruby_version, :source_path,
+                  :startup_command, :instance_id
+
+      def self.current
+        spec = defined?(Gem) && Gem.loaded_specs["igniter"]
+        new(
+          gem_version: Igniter::VERSION,
+          ruby_version: RUBY_VERSION,
+          source_path: spec&.gem_dir || File.expand_path("../../..", __dir__),
+          startup_command: $PROGRAM_NAME,
+          instance_id: SecureRandom.uuid
+        )
+      end
+
+      def initialize(gem_version:, ruby_version:, source_path:, startup_command:, instance_id:)
+        @gem_version     = gem_version
+        @ruby_version    = ruby_version
+        @source_path     = source_path
+        @startup_command = startup_command
+        @instance_id     = instance_id
+        freeze
+      end
+
+      def to_h
+        {
+          gem_version: gem_version,
+          ruby_version: ruby_version,
+          source_path: source_path,
+          startup_command: startup_command,
+          instance_id: instance_id
+        }
+      end
+    end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/replication/network_topology.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Replication
+    # Thread-safe in-memory registry of known nodes in the deployment network.
+    #
+    # Updated by ReflectiveReplicationAgent as nodes are spawned, heartbeat-ed,
+    # or removed. Can be shared across agent handler invocations via state.
+    #
+    # @example
+    #   topology = NetworkTopology.new
+    #   topology.register(node_id: "abc", host: "10.0.0.2", capabilities: %i[local_llm container_runtime])
+    #   topology.nodes(capability: :local_llm) # => [NodeEntry]
+    #   topology.needs_capability_query?([:local_llm, :container_runtime]) # => false
+    class NetworkTopology
+      # Mutable record for a single live node (mutated only inside the Mutex).
+      NodeEntry = Struct.new(:node_id, :host, :profile,
+                             :registered_at, :last_seen_at, :healthy,
+                             keyword_init: true) do
+        def capabilities
+          profile&.capabilities || []
+        end
+
+        def tags
+          profile&.tags || []
+        end
+      end
+
+      def initialize
+        @nodes = {}
+        @mutex = Mutex.new
+      end
+
+      # Register or overwrite a node entry.
+      #
+      # @param node_id [String]
+      # @param host    [String]
+      # @param profile       [NodeProfile, nil]
+      # @param capabilities  [Array<Symbol>]
+      # @param tags          [Array<Symbol>]
+      # @return [NodeEntry]
+      def register(node_id:, host:, profile: nil, capabilities: [], tags: [])
+        now   = Time.now
+        profile ||= NodeProfile.new(capabilities: capabilities, tags: tags)
+        entry = NodeEntry.new(
+          node_id:       node_id,
+          host:          host,
+          profile:       profile,
+          registered_at: now,
+          last_seen_at:  now,
+          healthy:       true
+        )
+        @mutex.synchronize { @nodes[node_id] = entry }
+        entry
+      end
+
+      # Update last_seen_at for a known node (heartbeat).
+      #
+      # @param node_id [String]
+      # @return [Boolean] true if the node was found
+      def touch(node_id:)
+        @mutex.synchronize do
+          entry = @nodes[node_id]
+          return false unless entry
+
+          entry.last_seen_at = Time.now
+          true
+        end
+      end
+
+      # Mark a node as unhealthy (e.g. SSH unreachable).
+      #
+      # @param node_id [String]
+      # @return [Boolean] true if the node was found
+      def mark_unhealthy(node_id:)
+        @mutex.synchronize do
+          entry = @nodes[node_id]
+          return false unless entry
+
+          entry.healthy = false
+          true
+        end
+      end
+
+      # Remove a node from the topology.
+      #
+      # @param node_id [String]
+      # @return [NodeEntry, nil] the removed entry, or nil if not found
+      def remove(node_id:)
+        @mutex.synchronize { @nodes.delete(node_id) }
+      end
+
+      # Return nodes, optionally filtered by capability or query.
+      #
+      # @param capability [Symbol, String, nil]
+      # @param query [CapabilityQuery, Array<Symbol>, Hash, Symbol, String, nil]
+      # @return [Array<NodeEntry>]
+      def nodes(capability: nil, query: nil)
+        @mutex.synchronize do
+          entries = @nodes.values.dup
+          entries = entries.select { |e| e.capabilities.include?(capability.to_sym) } if capability
+          if query
+            normalized = CapabilityQuery.normalize(query)
+            entries = entries.select { |e| normalized.matches_profile?(e.profile) }
+          end
+          entries
+        end
+      end
+
+      # True when no healthy node with the given capability exists.
+      #
+      # @param capability [Symbol, String]
+      # @return [Boolean]
+      def needs_capability?(capability)
+        nodes(capability: capability).none?(&:healthy)
+      end
+
+      # True when no healthy node satisfies the capability query.
+      #
+      # @param query [CapabilityQuery, Array<Symbol>, Hash, Symbol, String]
+      # @return [Boolean]
+      def needs_capability_query?(query)
+        nodes(query: query).none?(&:healthy)
+      end
+
+      # Count of healthy nodes across all roles.
+      #
+      # @return [Integer]
+      def healthy_count
+        @mutex.synchronize { @nodes.values.count(&:healthy) }
+      end
+
+      # Total number of registered nodes.
+      #
+      # @return [Integer]
+      def size
+        @mutex.synchronize { @nodes.size }
+      end
+
+      # All registered node IDs.
+      #
+      # @return [Array<String>]
+      def node_ids
+        @mutex.synchronize { @nodes.keys.dup }
+      end
+    end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/replication/node_profile.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Replication
+      # Immutable snapshot of a node's observable runtime traits.
+      #
+      # Profiles bridge host discovery and cluster replication: a node can inspect
+      # its environment, derive capability coordinates, and advertise which
+      # capability queries it can currently satisfy.
+      class NodeProfile
+        DEFAULT_CAPABILITY_MAP = {
+          "ruby" => :ruby,
+          "bundle" => :ruby,
+          "rake" => :ruby,
+          "rspec" => :ruby,
+          "git" => :source_control,
+          "curl" => :http_client,
+          "wget" => :http_client,
+          "jq" => :json_cli,
+          "sqlite3" => :data_store,
+          "psql" => :data_store,
+          "redis-cli" => :data_store,
+          "python3" => :python,
+          "pip3" => :python,
+          "node" => :javascript,
+          "npm" => :javascript,
+          "yarn" => :javascript,
+          "pnpm" => :javascript,
+          "docker" => :container_runtime,
+          "docker-compose" => :container_runtime,
+          "ffmpeg" => :media_processing,
+          "ollama" => :local_llm,
+          "pio" => :embedded,
+          "arduino-cli" => :embedded,
+          "esptool.py" => :embedded,
+          "make" => :native_build,
+          "gcc" => :native_build,
+          "clang" => :native_build
+        }.freeze
+
+        attr_reader :hostname, :platform, :os, :cpu, :utilities,
+                    :capabilities, :tags, :metadata
+
+        def self.from_discovery(snapshot, capabilities: [], tags: [],
+                                capability_map: DEFAULT_CAPABILITY_MAP)
+          utility_candidates = Array(snapshot.dig(:paths, :utility_candidates))
+          discovered = utility_candidates.filter_map do |entry|
+            next unless entry[:present]
+
+            entry[:name].to_s
+          end
+
+          discovered |= Array(snapshot.dig(:paths, :discovered_executables)).map(&:to_s)
+          derived_capabilities = discovered.flat_map { |name| Array(capability_map[name]) }
+
+          new(
+            hostname:     snapshot.dig(:host, :hostname),
+            platform:     snapshot.dig(:host, :platform),
+            os:           snapshot.dig(:host, :os),
+            cpu:          snapshot.dig(:host, :cpu),
+            utilities:    discovered,
+            capabilities: derived_capabilities + Array(capabilities),
+            tags:         inferred_tags(snapshot) + Array(tags),
+            metadata:     { generated_at: snapshot[:generated_at] }
+          )
+        end
+
+        def self.inferred_tags(snapshot)
+          tags = []
+          os   = snapshot.dig(:host, :os).to_s.downcase
+          cpu  = snapshot.dig(:host, :cpu).to_s
+
+          tags << :darwin if os.include?("darwin")
+          tags << :linux if os.include?("linux")
+          tags << cpu.tr("-", "_").to_sym unless cpu.empty?
+
+          ruby_engine = snapshot.dig(:runtime, :ruby, :engine).to_s
+          tags << ruby_engine.to_sym unless ruby_engine.empty?
+          tags
+        end
+
+        def initialize(hostname: nil, platform: nil, os: nil, cpu: nil,
+                       utilities: [], capabilities: [], tags: [], metadata: {})
+          @hostname     = hostname&.to_s
+          @platform     = platform&.to_s
+          @os           = os&.to_s
+          @cpu          = cpu&.to_s
+          @utilities    = Array(utilities).map(&:to_s).uniq.sort.freeze
+          @capabilities = Array(capabilities).map(&:to_sym).uniq.sort.freeze
+          @tags         = Array(tags).map(&:to_sym).uniq.sort.freeze
+          @metadata     = normalize_metadata(metadata).freeze
+          freeze
+        end
+
+        def capability?(capability)
+          @capabilities.include?(capability.to_sym)
+        end
+
+        def tag?(tag)
+          @tags.include?(tag.to_sym)
+        end
+
+        def to_h
+          {
+            hostname: @hostname,
+            platform: @platform,
+            os: @os,
+            cpu: @cpu,
+            utilities: @utilities,
+            capabilities: @capabilities,
+            tags: @tags,
+            metadata: @metadata
+          }
+        end
+
+        private
+
+        def normalize_metadata(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key.to_sym] = normalize_metadata(nested)
+            end
+          when Array
+            value.map { |item| normalize_metadata(item) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end