igniter 0.4.5 → 0.5.1

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

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "replication_agent"
+require_relative "network_topology"
+require_relative "expansion_plan"
+require_relative "expansion_planner"
+require_relative "capability_query"
+require_relative "node_profile"
+
+module Igniter
+  module Cluster
+    module Replication
+    # ReplicationAgent extended with episodic memory, self-reflection, and
+    # topology-aware network expansion.
+    #
+    # == Additional message types
+    #
+    #   :assess_network  — run ExpansionPlanner; execute replicate_capabilities/retire_node actions
+    #   :reflect         — run a ReflectionCycle over recent episodes; store summary in state
+    #   :register_node   — register a remote node in the local NetworkTopology
+    #   :node_heartbeat  — update last_seen_at for a known node
+    #   :signal_scale    — emit a :scale_signal episode for a capability query
+    #
+    # == State keys (in addition to inherited :events)
+    #
+    #   :topology        — NetworkTopology instance (created lazily on first access)
+    #   :host_pool       — Array<String> of candidate hosts
+    #   :required_capabilities — Array<CapabilityQuery-ish> that must always be present
+    #   :last_plan       — Hash from the most recent ExpansionPlan
+    #   :last_reflection — String summary from the most recent reflection cycle
+    #
+    # == Memory
+    #
+    # Call +enable_class_memory+ in the class body to activate episodic memory.
+    # Memory is class-level (shared across handler invocations on this class).
+    #
+    # == Auto-assessment
+    #
+    # Call +auto_assess(every: N)+ to schedule periodic topology assessment.
+    #
+    # @example
+    #   class MyAgent < ReflectiveReplicationAgent
+    #     enable_class_memory
+    #     auto_assess every: 60
+    #   end
+    #
+    #   ref = MyAgent.start(initial_state: {
+    #     topology:              NetworkTopology.new,
+    #     required_capabilities: [[:local_llm]],
+    #     host_pool:             ["10.0.0.2", "10.0.0.3"]
+    #   })
+    #   ref.call(:assess_network)
+    class ReflectiveReplicationAgent < ReplicationAgent
+      initial_state topology: nil, host_pool: [], required_capabilities: [],
+                    last_plan: nil, last_reflection: nil
+
+      # ── Class-level memory ─────────────────────────────────────────────────────
+
+      class << self
+        # Activate episodic memory for this class.
+        #
+        # @param store [Memory::Store, nil] backing store; defaults to global default
+        # @return [void]
+        def enable_class_memory(store: nil)
+          require "igniter/core/memory"
+          @class_memory_store   = store || Igniter::Memory.default_store
+          @class_memory_enabled = true
+        end
+
+        # Returns true when class-level memory has been activated.
+        #
+        # @return [Boolean]
+        def class_memory_enabled?
+          @class_memory_enabled || false
+        end
+
+        # Returns the AgentMemory facade bound to this class, or nil when disabled.
+        #
+        # @return [Memory::AgentMemory, nil]
+        def class_memory
+          return nil unless class_memory_enabled?
+
+          @class_memory ||= Igniter::Memory::AgentMemory.new(
+            store:    @class_memory_store,
+            agent_id: name.to_s
+          )
+        end
+
+        # Reset class-level memory state. Intended for use in tests.
+        #
+        # @return [void]
+        def reset_class_memory!
+          @class_memory         = nil
+          @class_memory_store   = nil
+          @class_memory_enabled = false
+        end
+
+        # Register a recurring topology assessment.
+        #
+        # @param every [Numeric] interval in seconds
+        # @return [void]
+        def auto_assess(every:)
+          schedule(:auto_assessment, every: every) do |state:|
+            agent = new
+            agent.send(:run_assess_network, state, {})
+          end
+        end
+      end
+
+      # ── deliver: intercept lifecycle events into memory ────────────────────────
+
+      # Override the no-op deliver from ReplicationAgent to record events.
+      # Subclasses can call +super+ and then add their own routing.
+      #
+      # @param type    [Symbol]
+      # @param payload [Hash]
+      def deliver(type, payload = {})
+        self.class.class_memory&.record(
+          type:       :replication_event,
+          content:    "#{type}: #{payload.inspect}",
+          outcome:    type == :replication_failed ? "failure" : "success",
+          importance: 0.6
+        )
+      end
+
+      # ── Handlers ───────────────────────────────────────────────────────────────
+
+      # Re-define :replicate (parent's handler is cleared by Agent.inherited).
+      on :replicate do |state:, payload:, **|
+        agent = new
+        agent.send(:run_replicate, payload)
+        state
+      end
+
+      on :assess_network do |state:, payload:, **|
+        agent = new
+        agent.send(:run_assess_network, state, payload)
+      end
+
+      on :reflect do |state:, payload:, **|
+        next state unless class_memory_enabled?
+
+        rec = class_memory.reflect
+        class_memory.record(
+          type:       :reflection,
+          content:    rec.summary,
+          outcome:    "success",
+          importance: 0.8
+        )
+        state.merge(last_reflection: rec.summary)
+      end
+
+      on :register_node do |state:, payload:, **|
+        topology = state[:topology] || NetworkTopology.new
+        agent    = new
+        profile  = payload[:profile] || agent.send(:build_profile_from_payload, payload)
+
+        topology.register(
+          node_id: payload.fetch(:node_id),
+          host:    payload.fetch(:host),
+          profile: profile
+        )
+        state.merge(topology: topology)
+      end
+
+      on :node_heartbeat do |state:, payload:, **|
+        state[:topology]&.touch(node_id: payload.fetch(:node_id))
+        state
+      end
+
+      on :signal_scale do |state:, payload:, **|
+        query = CapabilityQuery.normalize(payload[:query] || payload[:capabilities] || payload.fetch(:capability))
+        class_memory&.record(
+          type:    :scale_signal,
+          content: "scale_out:#{query.compact_signature}",
+          outcome: nil
+        )
+        state
+      end
+
+      private
+
+      # Assess the network topology and execute the resulting plan.
+      # Returns the updated state hash.
+      #
+      # @param state   [Hash]
+      # @param payload [Hash]
+      # @return [Hash]
+      def run_assess_network(state, payload)
+        topology = state[:topology] || NetworkTopology.new
+        planner  = ExpansionPlanner.new(
+          topology:              topology,
+          memory:                self.class.class_memory,
+          required_capabilities: Array(payload[:required_capabilities] || state[:required_capabilities]),
+          host_pool:             Array(payload[:host_pool] || state[:host_pool])
+        )
+
+        plan = planner.plan
+
+        plan.actions.each do |action|
+          case action[:action]
+          when :replicate_capabilities
+            run_replicate_capabilities(action, topology)
+          when :retire_node
+            topology.remove(node_id: action[:node_id])
+            deliver(:node_retired, node_id: action[:node_id], host: action[:host])
+          end
+        end
+
+        self.class.class_memory&.record(
+          type:    :assessment,
+          content: plan.rationale.to_s,
+          outcome: "success"
+        )
+
+        state.merge(topology: topology, last_plan: plan.to_h)
+      end
+
+      # Execute a :replicate_capabilities action: call run_replicate + register in topology.
+      #
+      # @param action   [Hash]
+      # @param topology [NetworkTopology]
+      def run_replicate_capabilities(action, topology)
+        run_replicate(
+          host:                 action.fetch(:host),
+          user:                 action.fetch(:user, "deploy"),
+          strategy:             action.fetch(:strategy, :git),
+          env:                  action.fetch(:env, {}),
+          bootstrapper_options: action.fetch(:bootstrapper_options, {})
+        )
+
+        query = CapabilityQuery.normalize(action.fetch(:query))
+        profile = NodeProfile.new(capabilities: query.all_of, tags: query.tags)
+        topology.register(node_id: SecureRandom.uuid, host: action[:host], profile: profile)
+        deliver(:capabilities_replicated, host: action[:host], query: query.to_h)
+      end
+
+      def build_profile_from_payload(payload)
+        return payload[:profile] if payload[:profile].is_a?(NodeProfile)
+
+        discovery = payload[:discovery]
+        if discovery
+          NodeProfile.from_discovery(
+            discovery,
+            capabilities: Array(payload[:capabilities]),
+            tags:         Array(payload[:tags])
+          )
+        else
+          NodeProfile.new(
+            capabilities: Array(payload[:capabilities]),
+            tags:         Array(payload[:tags])
+          )
+        end
+      end
+    end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "igniter/agent"
+
+module Igniter
+  module Cluster
+    module Replication
+    # Agent that handles :replicate messages to deploy Igniter to remote servers.
+    #
+    # In production, start via ReplicationAgent.start and send messages through
+    # the Ref. In tests, instantiate directly and call handle_message/1.
+    #
+    # Message payload keys:
+    #   host:                  [String]  (required) remote hostname or IP
+    #   user:                  [String]  (required) SSH username
+    #   key:                   [String]  path to SSH private key (optional)
+    #   port:                  [Integer] SSH port (default: 22)
+    #   env:                   [Hash]    environment variables for remote (default: {})
+    #   strategy:              [Symbol]  :git, :gem, or :tarball (default: :git)
+    #   target_path:           [String]  installation path on remote (default: /opt/igniter)
+    #   bootstrapper_options:  [Hash]    forwarded to the bootstrapper constructor
+    #
+    class ReplicationAgent < Igniter::Agent
+      MAX_REPLICAS = 10
+
+      initial_state events: []
+
+      # Class-level handler for the agent mailbox runtime.
+      # Instantiates a temporary agent to run the replication so that
+      # deliver/1 can be overridden in subclasses.
+      on :replicate do |state:, payload:, **|
+        agent = new
+        agent.send(:run_replicate, payload)
+        state
+      end
+
+      # Emit a named lifecycle event. Override or stub in tests.
+      #
+      # @param type    [Symbol] event name (e.g. :replication_started)
+      # @param payload [Hash]   associated data
+      def deliver(type, payload = {})
+        # Base implementation: no-op. Override in subclasses for real routing.
+      end
+
+      # Process a raw message hash synchronously (used in tests and internal tooling).
+      #
+      # @param message [Hash] must have :type key; optional :payload key
+      def handle_message(message)
+        type    = message.fetch(:type).to_sym
+        payload = message.fetch(:payload, {})
+        return unless type == :replicate
+
+        run_replicate(payload)
+      end
+
+      private
+
+      def run_replicate(payload) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        host        = payload[:host]        || raise(ArgumentError, "host is required")
+        user        = payload[:user]        || raise(ArgumentError, "user is required")
+        key         = payload[:key]
+        port        = payload.fetch(:port, 22)
+        env         = payload.fetch(:env, {})
+        strategy    = payload.fetch(:strategy, :git).to_sym
+        target_path = payload.fetch(:target_path, "/opt/igniter")
+        bs_options  = payload.fetch(:bootstrapper_options, {})
+
+        session      = SSHSession.new(host: host, user: user, key: key, port: port)
+        bootstrapper = Replication.bootstrapper_for(strategy, **bs_options)
+        manifest     = Manifest.current
+
+        deliver(:replication_started, host: host, instance_id: manifest.instance_id)
+
+        bootstrapper.install(session: session, manifest: manifest,
+                             env: env, target_path: target_path)
+        bootstrapper.start(session: session, manifest: manifest, target_path: target_path)
+        verified = bootstrapper.verify(session: session, target_path: target_path)
+
+        deliver(:replication_completed,
+                host: host, instance_id: manifest.instance_id, verified: verified)
+      rescue SSHSession::SSHError => e
+        deliver(:replication_failed, host: host, error: e.message)
+      rescue ArgumentError => e
+        deliver(:replication_failed, host: payload[:host], error: e.message)
+      end
+    end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Igniter
+  module Cluster
+    module Replication
+    # Thin subprocess wrapper over the +ssh+ and +scp+ CLI tools.
+    #
+    # Provides exec/exec! for running remote commands and upload! for
+    # copying local files to the remote host. No external gems required.
+    class SSHSession
+      class SSHError < Igniter::Error; end
+
+      DEFAULT_CONNECT_TIMEOUT = 10
+
+      def initialize(host:, user:, key: nil, port: 22, connect_timeout: DEFAULT_CONNECT_TIMEOUT)
+        @host            = host
+        @user            = user
+        @key             = key
+        @port            = port
+        @connect_timeout = connect_timeout
+      end
+
+      # Run a command on the remote host. Raises SSHError on non-zero exit.
+      # Returns stdout string on success.
+      def exec!(command)
+        result = exec(command)
+        raise SSHError, "SSH command failed on #{@host}: #{command.inspect}\n#{result[:stderr]}" \
+          unless result[:success]
+
+        result[:stdout]
+      end
+
+      # Run a command on the remote host.
+      # Returns a Hash: { stdout:, stderr:, success:, exit_code: }
+      def exec(command)
+        stdout, stderr, status = Open3.capture3(*build_cmd(command))
+        { stdout: stdout, stderr: stderr, success: status.success?, exit_code: status.exitstatus }
+      end
+
+      # Upload a local file to the remote host via scp.
+      # Raises SSHError on failure.
+      def upload!(local_path, remote_path)
+        args = ["scp", *scp_opts, "-P", @port.to_s, local_path, "#{@user}@#{@host}:#{remote_path}"]
+        _, stderr, status = Open3.capture3(*args)
+        raise SSHError, "SCP upload failed to #{@host}: #{stderr}" unless status.success?
+      end
+
+      # Quick connectivity test. Returns true if the remote responds.
+      def test_connection
+        exec("echo ok")[:success]
+      end
+
+      private
+
+      def build_cmd(command)
+        ["ssh", *ssh_opts, "-p", @port.to_s, "#{@user}@#{@host}", command]
+      end
+
+      def ssh_opts
+        opts = [
+          "-o", "StrictHostKeyChecking=no",
+          "-o", "BatchMode=yes",
+          "-o", "ConnectTimeout=#{@connect_timeout}"
+        ]
+        opts += ["-i", @key] if @key
+        opts
+      end
+
+      def scp_opts
+        opts = ["-o", "StrictHostKeyChecking=no", "-B"]
+        opts += ["-i", @key] if @key
+        opts
+      end
+    end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "replication/manifest"
+require_relative "replication/ssh_session"
+require_relative "replication/bootstrapper"
+require_relative "replication/bootstrappers/git"
+require_relative "replication/bootstrappers/gem"
+require_relative "replication/bootstrappers/tarball"
+require_relative "replication/replication_agent"
+require_relative "replication/capability_query"
+require_relative "replication/node_profile"
+require_relative "replication/network_topology"
+require_relative "replication/expansion_plan"
+require_relative "replication/expansion_planner"
+require_relative "replication/reflective_replication_agent"
+
+module Igniter
+  module Cluster
+    # Deployment and self-replication capabilities for clustered nodes.
+    module Replication
+      ReplicationError = Class.new(Igniter::Error) unless const_defined?(:ReplicationError, false)
+
+      BOOTSTRAPPERS = {
+        git: Bootstrappers::Git,
+        gem: Bootstrappers::Gem,
+        tarball: Bootstrappers::Tarball
+      }.freeze unless const_defined?(:BOOTSTRAPPERS, false)
+
+      def self.bootstrapper_for(strategy, **options)
+        klass = BOOTSTRAPPERS.fetch(strategy.to_sym) do
+          raise ArgumentError,
+                "Unknown bootstrapper: #{strategy}. Available: #{BOOTSTRAPPERS.keys.join(", ")}"
+        end
+        klass.new(**options)
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/routed_agent_adapter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    # Cluster-aware routed adapter for agent nodes.
+    class RoutedAgentAdapter < Igniter::Runtime::ProxyAgentAdapter
+      def initialize(local_adapter: Igniter::Runtime::RegistryAgentAdapter.new,
+                     route_resolver: AgentRouteResolver.new,
+                     transport: Igniter::Server.agent_transport)
+        super(local_adapter: local_adapter, route_resolver: route_resolver, transport: transport)
+      end
+
+      def call(node:, inputs:, execution: nil)
+        super
+      rescue Igniter::Cluster::Mesh::DeferredCapabilityError => error
+        pending(node, error)
+      rescue Igniter::Cluster::Mesh::IncidentError => error
+        failure(node, error)
+      end
+
+      def cast(node:, inputs:, execution: nil)
+        super
+      rescue Igniter::Cluster::Mesh::DeferredCapabilityError => error
+        pending(node, error)
+      rescue Igniter::Cluster::Mesh::IncidentError => error
+        failure(node, error)
+      end
+
+      private
+
+      def pending(node, error)
+        payload = error.deferred_result.payload
+        payload = payload.merge(routing_trace: error.explanation) if error.explanation
+
+        {
+          status: :pending,
+          message: error.message,
+          deferred_result: error.deferred_result,
+          payload: payload,
+          agent_trace: compact_trace(
+            adapter: :cluster_routed,
+            via: node.agent_name,
+            message: node.message_name,
+            routing_mode: :capability,
+            capability: error.capability,
+            capability_query: error.query,
+            local: false,
+            remote: true,
+            outcome: :pending,
+            reason: :routing_deferred
+          )
+        }
+      end
+
+      def failure(node, error)
+        {
+          status: :failed,
+          error: { message: error.message },
+          agent_trace: compact_trace(
+            adapter: :cluster_routed,
+            via: node.agent_name,
+            message: node.message_name,
+            routing_mode: :pinned,
+            pinned_to: error.peer_name,
+            local: false,
+            remote: true,
+            reason: :routing_incident
+          )
+        }
+      end
+
+      def compact_trace(**trace)
+        trace.each_with_object({}) do |(key, value), memo|
+          memo[key] = value unless value.nil?
+        end
+      end
+    end
+  end
+end