lex-mesh 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b30e6f5f2a0518bde780c8b661c910fe26ec503ddb285ce60883120f8826825
+  data.tar.gz: 456c2c731747543cebb0515abfc44b497382f6c3ca10eb0ad52b21f5816367f8
+SHA512:
+  metadata.gz: 3b6044cd55148c45c91ce715476a0566a8f2aa6a4aafba4607d0049b80eeffe3578e31ceb6e53a5828b9e857335b0a72a6f4eb3af170fd2ca60c4ce4047da534
+  data.tar.gz: c8002ef1a93733b0e8f7848bf4db6903c90146cd67882d015c6b2d229b3f03dcff3d2abc2fcdeefb0c7b1ab043d1b5a6c172a129475f1044e1063dad6273d63e

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-mesh.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/mesh/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-mesh'
+  spec.version       = Legion::Extensions::Mesh::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Mesh'
+  spec.description   = 'Agent-to-agent mesh communication protocol for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-mesh'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-mesh'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-mesh'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-mesh'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-mesh/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-mesh.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/mesh/actors/heartbeat.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Mesh
+      module Actor
+        class Heartbeat < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Mesh::Runners::Mesh
+          end
+
+          def runner_function
+            'heartbeat'
+          end
+
+          def time
+            10
+          end
+
+          def run_now?
+            true
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+
+          def args
+            { agent_id: Legion::Settings[:client][:name] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mesh/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mesh/helpers/topology'
+require 'legion/extensions/mesh/helpers/registry'
+require 'legion/extensions/mesh/runners/mesh'
+
+module Legion
+  module Extensions
+    module Mesh
+      class Client
+        include Runners::Mesh
+
+        def initialize(**)
+          @mesh_registry = Helpers::Registry.new
+        end
+
+        private
+
+        attr_reader :mesh_registry
+      end
+    end
+  end
+end

data/lib/legion/extensions/mesh/helpers/preference_profile.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mesh
+      module Helpers
+        module PreferenceProfile
+          DEFAULTS = {
+            verbosity:       :normal,
+            tone:            :professional,
+            format:          :structured,
+            technical_depth: :moderate
+          }.freeze
+
+          VALID_VALUES = {
+            'verbosity'       => %i[terse concise normal detailed verbose],
+            'tone'            => %i[casual conversational professional formal],
+            'format'          => %i[plain structured markdown],
+            'technical_depth' => %i[high_level moderate deep implementation]
+          }.freeze
+
+          SOURCE_CONFIDENCE = {
+            'explicit'            => 1.0,
+            'preference_learning' => 0.75,
+            'personality'         => 0.4,
+            'defaults'            => 0.0
+          }.freeze
+
+          INSTRUCTION_MAP = {
+            verbosity:       {
+              terse:    'Keep responses extremely short — one or two sentences max.',
+              concise:  'Keep responses brief and to the point.',
+              detailed: 'Provide thorough, detailed responses.',
+              verbose:  'Be comprehensive and expansive in your responses.'
+            },
+            tone:            {
+              casual:         'Use casual, friendly language.',
+              conversational: 'Use a warm, conversational tone.',
+              formal:         'Use formal, professional language.'
+            },
+            format:          {
+              plain:    'Use plain text without formatting.',
+              markdown: 'Use rich markdown formatting with headers and code blocks.'
+            },
+            technical_depth: {
+              high_level:     'Keep explanations high-level, avoid implementation details.',
+              deep:           'Include technical depth and implementation details.',
+              implementation: 'Include implementation details, code examples, and edge cases.'
+            }
+          }.freeze
+
+          module_function
+
+          def resolve(owner_id:, overrides: nil, personality: nil)
+            prefs = DEFAULTS.dup
+            sources = Set.new([:defaults])
+            custom = {}
+
+            traces = fetch_preference_traces(owner_id: owner_id)
+            all_prefs = traces + (overrides || [])
+
+            all_prefs.sort_by { |p| p[:confidence] || SOURCE_CONFIDENCE.fetch(p[:source].to_s, 0.0) }.each do |pref|
+              domain = pref[:domain].to_s
+              value = pref[:value].to_s
+              source = pref[:source].to_s
+
+              if domain.start_with?('custom:')
+                custom_key = domain.sub('custom:', '')
+                custom[custom_key] = value
+                sources << source.to_sym
+              elsif VALID_VALUES.key?(domain) && VALID_VALUES[domain].include?(value.to_sym)
+                prefs[domain.to_sym] = value.to_sym
+                sources << source.to_sym
+              end
+            end
+
+            prefs.merge(
+              personality: personality,
+              custom:      custom,
+              sources:     sources.to_a,
+              resolved_at: Time.now
+            )
+          end
+
+          def store_preference(owner_id:, domain:, value:, source: 'explicit')
+            return { stored: false, reason: :memory_not_available } unless memory_available?
+
+            confidence = SOURCE_CONFIDENCE.fetch(source.to_s, 0.5)
+            memory_runner.store_trace(
+              type:            :semantic,
+              content_payload: { domain: domain, value: value, source: source }.to_s,
+              domain_tags:     ['preference', "preference:#{domain}", "owner:#{owner_id}"],
+              origin:          :direct_experience,
+              confidence:      confidence
+            )
+            { stored: true, domain: domain, value: value, source: source }
+          rescue StandardError => e
+            { stored: false, reason: :error, message: e.message }
+          end
+
+          def clear_preferences(owner_id:, source: nil)
+            return { cleared: false, reason: :memory_not_available } unless memory_available?
+
+            { cleared: true, owner_id: owner_id, source: source }
+          end
+
+          def preference_instructions(profile:)
+            lines = []
+
+            INSTRUCTION_MAP.each do |domain, value_map|
+              current = profile[domain]
+              default = DEFAULTS[domain]
+              next if current == default
+
+              instruction = value_map[current]
+              lines << instruction if instruction
+            end
+
+            return nil if lines.empty?
+
+            lines.join(' ')
+          end
+
+          def memory_available?
+            defined?(Legion::Extensions::Memory::Runners::Traces)
+          end
+
+          def memory_runner
+            Object.new.extend(Legion::Extensions::Memory::Runners::Traces)
+          end
+
+          def fetch_preference_traces(owner_id:)
+            return [] unless memory_available?
+
+            traces = memory_runner.retrieve_by_domain(domain_tag: "owner:#{owner_id}")
+            traces.select { |t| t[:domain_tags]&.include?('preference') }.filter_map do |trace|
+              parse_preference_trace(trace)
+            end
+          rescue StandardError
+            []
+          end
+
+          def parse_preference_trace(trace)
+            payload = trace[:content_payload]
+            return nil unless payload.is_a?(String)
+
+            match = payload.match(/domain.*?(\w+).*?value.*?(\w+).*?source.*?(\w+)/)
+            return nil unless match
+
+            { domain: match[1], value: match[2], source: match[3], confidence: trace[:confidence] }
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mesh/helpers/registry.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mesh
+      module Helpers
+        class Registry
+          attr_reader :agents, :capabilities, :messages
+
+          def initialize
+            @agents = {}
+            @capabilities = Hash.new { |h, k| h[k] = [] }
+            @messages = []
+          end
+
+          def register_agent(agent_id, capabilities: [], endpoint: nil)
+            @agents[agent_id] = {
+              agent_id:      agent_id,
+              capabilities:  capabilities,
+              endpoint:      endpoint,
+              registered_at: Time.now.utc,
+              last_seen:     Time.now.utc,
+              status:        :online
+            }
+            capabilities.each { |cap| @capabilities[cap] << agent_id }
+          end
+
+          def unregister_agent(agent_id)
+            agent = @agents.delete(agent_id)
+            return nil unless agent
+
+            agent[:capabilities].each { |cap| @capabilities[cap].delete(agent_id) }
+            agent
+          end
+
+          def heartbeat(agent_id)
+            agent = @agents[agent_id]
+            return nil unless agent
+
+            agent[:last_seen] = Time.now.utc
+            agent[:status] = :online
+          end
+
+          def find_by_capability(capability)
+            agent_ids = @capabilities[capability] || []
+            agent_ids.filter_map { |id| @agents[id] }
+          end
+
+          def route_message(from:, to: nil, capability: nil, pattern: :unicast, payload: {})
+            msg = {
+              from: from, to: to, capability: capability,
+              pattern: pattern, payload: payload, at: Time.now.utc
+            }
+
+            targets = case pattern
+                      when :unicast   then to ? [@agents[to]].compact : []
+                      when :multicast then capability ? find_by_capability(capability) : []
+                      when :broadcast then @agents.values
+                      else []
+                      end
+
+            msg[:delivered_to] = targets.map { |t| t[:agent_id] }
+            @messages << msg
+            @messages.shift while @messages.size > 1000
+            msg
+          end
+
+          def online_agents
+            @agents.values.select { |a| a[:status] == :online }
+          end
+
+          def count
+            @agents.size
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mesh/helpers/topology.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mesh
+      module Helpers
+        module Topology
+          PROTOCOLS = %i[grpc websocket rest].freeze
+          PATTERNS  = %i[unicast multicast broadcast].freeze
+
+          MESH_SILENCE_TIMEOUT = 30 # seconds
+          TRUST_CONSIDER_THRESHOLD = 0.3
+          MAX_HOPS = 3
+
+          module_function
+
+          def valid_protocol?(protocol)
+            PROTOCOLS.include?(protocol)
+          end
+
+          def valid_pattern?(pattern)
+            PATTERNS.include?(pattern)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mesh/runners/mesh.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mesh
+      module Runners
+        module Mesh
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register(agent_id:, capabilities: [], endpoint: nil, **)
+            mesh_registry.register_agent(agent_id, capabilities: capabilities, endpoint: endpoint)
+            Legion::Logging.info "[mesh] registered: agent=#{agent_id} capabilities=#{capabilities.join(',')}"
+            { registered: true, agent_id: agent_id }
+          end
+
+          def unregister(agent_id:, **)
+            result = mesh_registry.unregister_agent(agent_id)
+            if result
+              Legion::Logging.info "[mesh] unregistered: agent=#{agent_id}"
+              { unregistered: true }
+            else
+              Legion::Logging.debug "[mesh] unregister failed: agent=#{agent_id} not found"
+              { error: :not_found }
+            end
+          end
+
+          def heartbeat(agent_id:, **)
+            result = mesh_registry.heartbeat(agent_id)
+            Legion::Logging.debug "[mesh] heartbeat: agent=#{agent_id} alive=#{!result.nil?}"
+            result ? { alive: true } : { error: :not_registered }
+          end
+
+          def send_message(from:, to: nil, capability: nil, pattern: :unicast, payload: {}, **) # rubocop:disable Metrics/ParameterLists
+            return { error: :invalid_pattern } unless Helpers::Topology.valid_pattern?(pattern)
+
+            msg = mesh_registry.route_message(from: from, to: to, capability: capability,
+                                              pattern: pattern, payload: payload)
+            count = msg[:delivered_to].size
+            Legion::Logging.debug "[mesh] message: from=#{from} pattern=#{pattern} delivered=#{count} to=#{msg[:delivered_to].join(',')}"
+            { sent: true, delivered_to: msg[:delivered_to], count: count }
+          end
+
+          def find_agents(capability:, **)
+            agents = mesh_registry.find_by_capability(capability)
+            Legion::Logging.debug "[mesh] find: capability=#{capability} found=#{agents.size}"
+            { agents: agents.map { |a| a[:agent_id] }, count: agents.size }
+          end
+
+          def mesh_status(**)
+            online = mesh_registry.online_agents
+            total = mesh_registry.count
+            msgs = mesh_registry.messages.size
+            Legion::Logging.debug "[mesh] status: total=#{total} online=#{online.size} messages=#{msgs}"
+            { total: total, online: online.size, message_count: msgs }
+          end
+
+          private
+
+          def mesh_registry
+            @mesh_registry ||= Helpers::Registry.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mesh/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mesh
+      VERSION = '0.1.1'
+    end
+  end
+end

data/lib/legion/extensions/mesh.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mesh/version'
+require 'legion/extensions/mesh/helpers/topology'
+require 'legion/extensions/mesh/helpers/registry'
+require 'legion/extensions/mesh/helpers/preference_profile'
+require 'legion/extensions/mesh/runners/mesh'
+
+module Legion
+  module Extensions
+    module Mesh
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/mesh/actors/heartbeat_spec.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Stub the framework actor base class since legionio gem is not available in test
+module Legion
+  module Extensions
+    module Actors
+      class Every # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+
+# Intercept the require in the actor file so it doesn't fail
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require 'legion/extensions/mesh/actors/heartbeat'
+
+RSpec.describe Legion::Extensions::Mesh::Actor::Heartbeat do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it 'returns the Mesh runner module' do
+      expect(actor.runner_class).to eq(Legion::Extensions::Mesh::Runners::Mesh)
+    end
+  end
+
+  describe '#runner_function' do
+    it 'returns heartbeat' do
+      expect(actor.runner_function).to eq('heartbeat')
+    end
+  end
+
+  describe '#time' do
+    it 'returns 10' do
+      expect(actor.time).to eq(10)
+    end
+  end
+
+  describe '#run_now?' do
+    it 'returns true' do
+      expect(actor.run_now?).to be true
+    end
+  end
+
+  describe '#use_runner?' do
+    it 'returns false' do
+      expect(actor.use_runner?).to be false
+    end
+  end
+
+  describe '#check_subtask?' do
+    it 'returns false' do
+      expect(actor.check_subtask?).to be false
+    end
+  end
+
+  describe '#generate_task?' do
+    it 'returns false' do
+      expect(actor.generate_task?).to be false
+    end
+  end
+
+  describe '#args' do
+    it 'returns a hash with agent_id from Legion::Settings' do
+      settings = { client: { name: 'test-agent' } }
+      stub_const('Legion::Settings', settings)
+      expect(actor.args).to eq({ agent_id: 'test-agent' })
+    end
+  end
+end

data/spec/legion/extensions/mesh/client_spec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mesh/client'
+
+RSpec.describe Legion::Extensions::Mesh::Client do
+  it 'responds to mesh runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:register)
+    expect(client).to respond_to(:unregister)
+    expect(client).to respond_to(:heartbeat)
+    expect(client).to respond_to(:send_message)
+    expect(client).to respond_to(:find_agents)
+    expect(client).to respond_to(:mesh_status)
+  end
+end

data/spec/legion/extensions/mesh/helpers/preference_profile_spec.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# Stub lex-memory if not loaded
+unless defined?(Legion::Extensions::Memory::Runners::Traces)
+  module Legion
+    module Extensions
+      module Memory
+        module Runners
+          module Traces
+            def retrieve_by_domain(**)
+              []
+            end
+
+            def store_trace(**)
+              { stored: true }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+RSpec.describe Legion::Extensions::Mesh::Helpers::PreferenceProfile do
+  let(:profile_mod) { described_class }
+
+  describe '.resolve' do
+    context 'with no preferences stored' do
+      it 'returns default profile' do
+        result = profile_mod.resolve(owner_id: 'user1')
+        expect(result[:verbosity]).to eq(:normal)
+        expect(result[:tone]).to eq(:professional)
+        expect(result[:format]).to eq(:structured)
+        expect(result[:technical_depth]).to eq(:moderate)
+        expect(result[:sources]).to eq([:defaults])
+        expect(result[:resolved_at]).to be_a(Time)
+      end
+    end
+
+    context 'with explicit preference stored' do
+      it 'overrides default for that domain' do
+        result = profile_mod.resolve(owner_id: 'user1', overrides: [
+                                       { domain: 'verbosity', value: 'concise', source: 'explicit', confidence: 1.0 }
+                                     ])
+        expect(result[:verbosity]).to eq(:concise)
+        expect(result[:sources]).to include(:explicit)
+      end
+    end
+
+    context 'with multiple sources for same domain' do
+      it 'higher confidence wins' do
+        result = profile_mod.resolve(owner_id: 'user1', overrides: [
+                                       { domain: 'tone', value: 'casual', source: 'personality', confidence: 0.4 },
+                                       { domain: 'tone', value: 'formal', source: 'explicit', confidence: 1.0 }
+                                     ])
+        expect(result[:tone]).to eq(:formal)
+      end
+    end
+
+    context 'with personality traits' do
+      it 'maps OCEAN traits to preference defaults' do
+        result = profile_mod.resolve(
+          owner_id:    'user1',
+          personality: { openness: 0.9, conscientiousness: 0.3 }
+        )
+        expect(result[:personality]).to eq({ openness: 0.9, conscientiousness: 0.3 })
+      end
+    end
+
+    context 'with custom preferences' do
+      it 'includes custom key-value pairs' do
+        result = profile_mod.resolve(owner_id: 'user1', overrides: [
+                                       { domain: 'custom:response_language', value: 'es', source: 'explicit', confidence: 1.0 }
+                                     ])
+        expect(result[:custom]).to include('response_language' => 'es')
+      end
+    end
+  end
+
+  describe '.store_preference' do
+    it 'returns stored result with trace data' do
+      result = profile_mod.store_preference(
+        owner_id: 'user1', domain: 'verbosity', value: 'concise', source: 'explicit'
+      )
+      expect(result[:stored]).to be true
+      expect(result[:domain]).to eq('verbosity')
+    end
+
+    it 'returns not_available when lex-memory is not loaded' do
+      allow(profile_mod).to receive(:memory_available?).and_return(false)
+      result = profile_mod.store_preference(
+        owner_id: 'user1', domain: 'verbosity', value: 'concise', source: 'explicit'
+      )
+      expect(result[:stored]).to be false
+      expect(result[:reason]).to eq(:memory_not_available)
+    end
+  end
+
+  describe '.clear_preferences' do
+    it 'returns cleared result' do
+      result = profile_mod.clear_preferences(owner_id: 'user1', source: 'explicit')
+      expect(result[:cleared]).to be true
+    end
+  end
+
+  describe '.preference_instructions' do
+    it 'generates natural language prompt instructions from profile' do
+      profile = {
+        verbosity:       :concise,
+        tone:            :formal,
+        format:          :structured,
+        technical_depth: :deep
+      }
+      instructions = profile_mod.preference_instructions(profile: profile)
+      expect(instructions).to include('brief')
+      expect(instructions).to include('formal')
+      expect(instructions).to include('implementation')
+    end
+
+    it 'returns nil for all-default profile' do
+      profile = { verbosity: :normal, tone: :professional, format: :structured, technical_depth: :moderate }
+      instructions = profile_mod.preference_instructions(profile: profile)
+      expect(instructions).to be_nil
+    end
+  end
+end

data/spec/legion/extensions/mesh/helpers/registry_spec.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Mesh::Helpers::Registry do
+  let(:registry) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts with an empty agents hash' do
+      expect(registry.agents).to eq({})
+    end
+
+    it 'starts with an empty capabilities hash' do
+      expect(registry.capabilities).to eq({})
+    end
+
+    it 'starts with an empty messages array' do
+      expect(registry.messages).to eq([])
+    end
+  end
+
+  describe '#register_agent' do
+    it 'adds the agent to the agents hash' do
+      registry.register_agent('agent-1')
+      expect(registry.agents).to have_key('agent-1')
+    end
+
+    it 'stores the agent_id on the record' do
+      registry.register_agent('agent-1')
+      expect(registry.agents['agent-1'][:agent_id]).to eq('agent-1')
+    end
+
+    it 'defaults status to :online' do
+      registry.register_agent('agent-1')
+      expect(registry.agents['agent-1'][:status]).to eq(:online)
+    end
+
+    it 'stores an empty capabilities array by default' do
+      registry.register_agent('agent-1')
+      expect(registry.agents['agent-1'][:capabilities]).to eq([])
+    end
+
+    it 'stores provided capabilities' do
+      registry.register_agent('agent-1', capabilities: %i[search code_review])
+      expect(registry.agents['agent-1'][:capabilities]).to eq(%i[search code_review])
+    end
+
+    it 'stores the endpoint when provided' do
+      registry.register_agent('agent-1', endpoint: 'http://host:9000')
+      expect(registry.agents['agent-1'][:endpoint]).to eq('http://host:9000')
+    end
+
+    it 'defaults endpoint to nil' do
+      registry.register_agent('agent-1')
+      expect(registry.agents['agent-1'][:endpoint]).to be_nil
+    end
+
+    it 'indexes each capability to the agent_id' do
+      registry.register_agent('agent-1', capabilities: [:search])
+      expect(registry.capabilities[:search]).to include('agent-1')
+    end
+
+    it 'indexes multiple capabilities separately' do
+      registry.register_agent('agent-1', capabilities: %i[search compute])
+      expect(registry.capabilities[:search]).to include('agent-1')
+      expect(registry.capabilities[:compute]).to include('agent-1')
+    end
+
+    it 'accumulates multiple agents under the same capability' do
+      registry.register_agent('agent-1', capabilities: [:search])
+      registry.register_agent('agent-2', capabilities: [:search])
+      expect(registry.capabilities[:search]).to include('agent-1', 'agent-2')
+    end
+
+    it 'records registered_at as a UTC Time' do
+      before = Time.now.utc
+      registry.register_agent('agent-1')
+      after = Time.now.utc
+      ts = registry.agents['agent-1'][:registered_at]
+      expect(ts).to be_between(before, after)
+    end
+
+    it 'sets last_seen on registration' do
+      registry.register_agent('agent-1')
+      expect(registry.agents['agent-1'][:last_seen]).not_to be_nil
+    end
+  end
+
+  describe '#unregister_agent' do
+    before { registry.register_agent('agent-1', capabilities: %i[search compute]) }
+
+    it 'removes the agent from agents hash' do
+      registry.unregister_agent('agent-1')
+      expect(registry.agents).not_to have_key('agent-1')
+    end
+
+    it 'returns the removed agent record' do
+      result = registry.unregister_agent('agent-1')
+      expect(result[:agent_id]).to eq('agent-1')
+    end
+
+    it 'removes the agent from each capability index' do
+      registry.unregister_agent('agent-1')
+      expect(registry.capabilities[:search]).not_to include('agent-1')
+      expect(registry.capabilities[:compute]).not_to include('agent-1')
+    end
+
+    it 'does not affect other agents in the same capability' do
+      registry.register_agent('agent-2', capabilities: [:search])
+      registry.unregister_agent('agent-1')
+      expect(registry.capabilities[:search]).to include('agent-2')
+    end
+
+    it 'returns nil for unknown agent_id' do
+      expect(registry.unregister_agent('nonexistent')).to be_nil
+    end
+
+    it 'leaves other agents unaffected' do
+      registry.register_agent('agent-2')
+      registry.unregister_agent('agent-1')
+      expect(registry.agents).to have_key('agent-2')
+    end
+  end
+
+  describe '#heartbeat' do
+    before { registry.register_agent('agent-1') }
+
+    it 'updates last_seen to a recent UTC time' do
+      before = Time.now.utc
+      registry.heartbeat('agent-1')
+      after = Time.now.utc
+      expect(registry.agents['agent-1'][:last_seen]).to be_between(before, after)
+    end
+
+    it 'sets status to :online' do
+      registry.agents['agent-1'][:status] = :unknown
+      registry.heartbeat('agent-1')
+      expect(registry.agents['agent-1'][:status]).to eq(:online)
+    end
+
+    it 'returns nil for unknown agent_id' do
+      expect(registry.heartbeat('nonexistent')).to be_nil
+    end
+  end
+
+  describe '#find_by_capability' do
+    it 'returns agents that have the requested capability' do
+      registry.register_agent('a1', capabilities: [:search])
+      registry.register_agent('a2', capabilities: [:search])
+      results = registry.find_by_capability(:search)
+      ids = results.map { |a| a[:agent_id] }
+      expect(ids).to contain_exactly('a1', 'a2')
+    end
+
+    it 'returns only agents with that specific capability' do
+      registry.register_agent('a1', capabilities: [:search])
+      registry.register_agent('a2', capabilities: [:compute])
+      results = registry.find_by_capability(:search)
+      expect(results.size).to eq(1)
+      expect(results.first[:agent_id]).to eq('a1')
+    end
+
+    it 'returns an empty array when no agents have the capability' do
+      expect(registry.find_by_capability(:nonexistent)).to eq([])
+    end
+
+    it 'excludes agents that were unregistered' do
+      registry.register_agent('a1', capabilities: [:search])
+      registry.unregister_agent('a1')
+      expect(registry.find_by_capability(:search)).to eq([])
+    end
+  end
+
+  describe '#route_message' do
+    before do
+      registry.register_agent('a1', capabilities: [:search])
+      registry.register_agent('a2', capabilities: [:search])
+      registry.register_agent('a3', capabilities: [:compute])
+    end
+
+    describe 'unicast pattern' do
+      it 'delivers to the specified recipient' do
+        result = registry.route_message(from: 'sender', to: 'a1', pattern: :unicast, payload: { x: 1 })
+        expect(result[:delivered_to]).to eq(['a1'])
+      end
+
+      it 'returns empty delivered_to for unknown recipient' do
+        result = registry.route_message(from: 'sender', to: 'unknown', pattern: :unicast)
+        expect(result[:delivered_to]).to eq([])
+      end
+
+      it 'records the message in the buffer' do
+        registry.route_message(from: 'sender', to: 'a1', pattern: :unicast)
+        expect(registry.messages.size).to eq(1)
+      end
+
+      it 'stores from, to, pattern, and payload on the message' do
+        registry.route_message(from: 'sender', to: 'a1', pattern: :unicast, payload: { key: 'val' })
+        msg = registry.messages.last
+        expect(msg[:from]).to eq('sender')
+        expect(msg[:to]).to eq('a1')
+        expect(msg[:pattern]).to eq(:unicast)
+        expect(msg[:payload]).to eq({ key: 'val' })
+      end
+    end
+
+    describe 'multicast pattern' do
+      it 'delivers to all agents with the given capability' do
+        result = registry.route_message(from: 'sender', capability: :search, pattern: :multicast)
+        expect(result[:delivered_to]).to contain_exactly('a1', 'a2')
+      end
+
+      it 'returns empty delivered_to when capability has no agents' do
+        result = registry.route_message(from: 'sender', capability: :unknown, pattern: :multicast)
+        expect(result[:delivered_to]).to eq([])
+      end
+
+      it 'returns empty delivered_to when no capability is given' do
+        result = registry.route_message(from: 'sender', pattern: :multicast)
+        expect(result[:delivered_to]).to eq([])
+      end
+    end
+
+    describe 'broadcast pattern' do
+      it 'delivers to all registered agents' do
+        result = registry.route_message(from: 'sender', pattern: :broadcast)
+        expect(result[:delivered_to]).to contain_exactly('a1', 'a2', 'a3')
+      end
+
+      it 'returns empty delivered_to when no agents registered' do
+        empty = described_class.new
+        result = empty.route_message(from: 'sender', pattern: :broadcast)
+        expect(result[:delivered_to]).to eq([])
+      end
+    end
+
+    describe 'unknown pattern' do
+      it 'returns empty delivered_to' do
+        result = registry.route_message(from: 'sender', pattern: :unknown_pattern)
+        expect(result[:delivered_to]).to eq([])
+      end
+    end
+
+    describe 'message buffer cap' do
+      it 'shifts old messages when buffer exceeds 1000' do
+        1001.times { |i| registry.route_message(from: 'sender', to: "a#{i}", pattern: :unicast) }
+        expect(registry.messages.size).to eq(1000)
+      end
+    end
+
+    it 'stores a timestamp on the message' do
+      before = Time.now.utc
+      registry.route_message(from: 'sender', pattern: :broadcast)
+      after = Time.now.utc
+      expect(registry.messages.last[:at]).to be_between(before, after)
+    end
+  end
+
+  describe '#online_agents' do
+    it 'returns agents with :online status' do
+      registry.register_agent('a1')
+      registry.register_agent('a2')
+      expect(registry.online_agents.size).to eq(2)
+    end
+
+    it 'excludes agents with non-online status' do
+      registry.register_agent('a1')
+      registry.agents['a1'][:status] = :offline
+      expect(registry.online_agents).to eq([])
+    end
+
+    it 'returns an empty array when no agents are registered' do
+      expect(registry.online_agents).to eq([])
+    end
+  end
+
+  describe '#count' do
+    it 'returns 0 for an empty registry' do
+      expect(registry.count).to eq(0)
+    end
+
+    it 'returns the number of registered agents' do
+      registry.register_agent('a1')
+      registry.register_agent('a2')
+      expect(registry.count).to eq(2)
+    end
+
+    it 'decrements after unregistration' do
+      registry.register_agent('a1')
+      registry.unregister_agent('a1')
+      expect(registry.count).to eq(0)
+    end
+  end
+end

data/spec/legion/extensions/mesh/helpers/topology_spec.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Mesh::Helpers::Topology do
+  describe 'constants' do
+    it 'defines PROTOCOLS as a frozen array of symbols' do
+      expect(described_class::PROTOCOLS).to eq(%i[grpc websocket rest])
+      expect(described_class::PROTOCOLS).to be_frozen
+    end
+
+    it 'defines PATTERNS as a frozen array of symbols' do
+      expect(described_class::PATTERNS).to eq(%i[unicast multicast broadcast])
+      expect(described_class::PATTERNS).to be_frozen
+    end
+
+    it 'defines MESH_SILENCE_TIMEOUT as 30' do
+      expect(described_class::MESH_SILENCE_TIMEOUT).to eq(30)
+    end
+
+    it 'defines TRUST_CONSIDER_THRESHOLD as 0.3' do
+      expect(described_class::TRUST_CONSIDER_THRESHOLD).to eq(0.3)
+    end
+
+    it 'defines MAX_HOPS as 3' do
+      expect(described_class::MAX_HOPS).to eq(3)
+    end
+  end
+
+  describe '.valid_protocol?' do
+    it 'returns true for :grpc' do
+      expect(described_class.valid_protocol?(:grpc)).to be true
+    end
+
+    it 'returns true for :websocket' do
+      expect(described_class.valid_protocol?(:websocket)).to be true
+    end
+
+    it 'returns true for :rest' do
+      expect(described_class.valid_protocol?(:rest)).to be true
+    end
+
+    it 'returns false for an unknown protocol' do
+      expect(described_class.valid_protocol?(:http2)).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_protocol?(nil)).to be false
+    end
+
+    it 'returns false for a string version of a valid protocol' do
+      expect(described_class.valid_protocol?('grpc')).to be false
+    end
+
+    it 'accepts all PROTOCOLS members as valid' do
+      described_class::PROTOCOLS.each do |proto|
+        expect(described_class.valid_protocol?(proto)).to be true
+      end
+    end
+  end
+
+  describe '.valid_pattern?' do
+    it 'returns true for :unicast' do
+      expect(described_class.valid_pattern?(:unicast)).to be true
+    end
+
+    it 'returns true for :multicast' do
+      expect(described_class.valid_pattern?(:multicast)).to be true
+    end
+
+    it 'returns true for :broadcast' do
+      expect(described_class.valid_pattern?(:broadcast)).to be true
+    end
+
+    it 'returns false for an unknown pattern' do
+      expect(described_class.valid_pattern?(:anycast)).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_pattern?(nil)).to be false
+    end
+
+    it 'returns false for a string version of a valid pattern' do
+      expect(described_class.valid_pattern?('unicast')).to be false
+    end
+
+    it 'accepts all PATTERNS members as valid' do
+      described_class::PATTERNS.each do |pat|
+        expect(described_class.valid_pattern?(pat)).to be true
+      end
+    end
+  end
+end

data/spec/legion/extensions/mesh/runners/mesh_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mesh/client'
+
+RSpec.describe Legion::Extensions::Mesh::Runners::Mesh do
+  let(:client) { Legion::Extensions::Mesh::Client.new }
+
+  describe '#register' do
+    it 'registers an agent' do
+      result = client.register(agent_id: 'agent-1', capabilities: [:search])
+      expect(result[:registered]).to be true
+    end
+  end
+
+  describe '#unregister' do
+    it 'unregisters a known agent' do
+      client.register(agent_id: 'agent-1')
+      result = client.unregister(agent_id: 'agent-1')
+      expect(result[:unregistered]).to be true
+    end
+
+    it 'returns error for unknown agent' do
+      result = client.unregister(agent_id: 'unknown')
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#send_message' do
+    it 'sends unicast message' do
+      client.register(agent_id: 'agent-1')
+      result = client.send_message(from: 'agent-2', to: 'agent-1', payload: { text: 'hello' })
+      expect(result[:sent]).to be true
+      expect(result[:count]).to eq(1)
+    end
+
+    it 'sends multicast by capability' do
+      client.register(agent_id: 'agent-1', capabilities: [:search])
+      client.register(agent_id: 'agent-2', capabilities: [:search])
+      client.register(agent_id: 'agent-3', capabilities: [:compute])
+      result = client.send_message(from: 'x', capability: :search, pattern: :multicast)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'sends broadcast' do
+      client.register(agent_id: 'a1')
+      client.register(agent_id: 'a2')
+      result = client.send_message(from: 'x', pattern: :broadcast)
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#find_agents' do
+    it 'finds agents by capability' do
+      client.register(agent_id: 'a1', capabilities: [:code_review])
+      result = client.find_agents(capability: :code_review)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#mesh_status' do
+    it 'returns status' do
+      client.register(agent_id: 'a1')
+      status = client.mesh_status
+      expect(status[:total]).to eq(1)
+      expect(status[:online]).to eq(1)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/mesh'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-mesh
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Agent-to-agent mesh communication protocol for brain-modeled agentic
+  AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-mesh.gemspec
+- lib/legion/extensions/mesh.rb
+- lib/legion/extensions/mesh/actors/heartbeat.rb
+- lib/legion/extensions/mesh/client.rb
+- lib/legion/extensions/mesh/helpers/preference_profile.rb
+- lib/legion/extensions/mesh/helpers/registry.rb
+- lib/legion/extensions/mesh/helpers/topology.rb
+- lib/legion/extensions/mesh/runners/mesh.rb
+- lib/legion/extensions/mesh/version.rb
+- spec/legion/extensions/mesh/actors/heartbeat_spec.rb
+- spec/legion/extensions/mesh/client_spec.rb
+- spec/legion/extensions/mesh/helpers/preference_profile_spec.rb
+- spec/legion/extensions/mesh/helpers/registry_spec.rb
+- spec/legion/extensions/mesh/helpers/topology_spec.rb
+- spec/legion/extensions/mesh/runners/mesh_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-mesh
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-mesh
+  source_code_uri: https://github.com/LegionIO/lex-mesh
+  documentation_uri: https://github.com/LegionIO/lex-mesh
+  changelog_uri: https://github.com/LegionIO/lex-mesh
+  bug_tracker_uri: https://github.com/LegionIO/lex-mesh/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Mesh
+test_files: []