lex-mirror 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c3e497d574566a1b283837eff61746dacf6be493caaf2720ccb74c7ce8d6b332
+  data.tar.gz: a13b1c4de5ff079a611b9933196cc375e70cf4c78cab9e484513ea0f01599d02
+SHA512:
+  metadata.gz: 64e7a587ef7c672da68005abdbf9b52fdb7f68fe1cc6191d9df2728f56677f02c63c5a9a9c771d1a9ea810b9c81ab11cc6446c893f91d8437e6bee6a3db69853
+  data.tar.gz: 8c02d2159b5d3b7bbc97ff75043703b165aa974b5877723606993a56f658a4132dd0b0fe0698621418d664ce6cc1200db125a8817298bf741ee45f9cd1816297

data/Gemfile

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

data/lex-mirror.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/mirror/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-mirror'
+  spec.version       = Legion::Extensions::Mirror::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Mirror'
+  spec.description   = 'Mirror neuron system for brain-modeled agentic AI — automatic behavioral ' \
+                       'observation, imitation learning with fidelity tracking, and empathic ' \
+                       'resonance from watching other agents act.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-mirror'
+  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-mirror'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-mirror'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-mirror'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-mirror/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-mirror.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/mirror/actors/decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Mirror
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Mirror::Runners::Mirror
+          end
+
+          def runner_function
+            'update_mirror'
+          end
+
+          def time
+            120
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mirror/helpers/constants'
+require 'legion/extensions/mirror/helpers/observed_behavior'
+require 'legion/extensions/mirror/helpers/mirror_system'
+require 'legion/extensions/mirror/runners/mirror'
+
+module Legion
+  module Extensions
+    module Mirror
+      class Client
+        include Runners::Mirror
+
+        def initialize(mirror_system: nil, **)
+          @mirror_system = mirror_system || Helpers::MirrorSystem.new
+        end
+
+        private
+
+        attr_reader :mirror_system
+      end
+    end
+  end
+end

data/lib/legion/extensions/mirror/helpers/constants.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mirror
+      module Helpers
+        module Constants
+          # Maximum observed behaviors to store
+          MAX_OBSERVATIONS = 200
+
+          # Maximum imitation candidates per domain
+          MAX_IMITATIONS = 50
+
+          # How quickly observed behaviors are internalized
+          MIRROR_ALPHA = 0.15
+
+          # Default resonance strength for new observations
+          DEFAULT_RESONANCE = 0.3
+
+          # Minimum resonance to keep an observation
+          RESONANCE_FLOOR = 0.05
+
+          # Resonance decay per tick
+          RESONANCE_DECAY = 0.01
+
+          # Boost when observation matches own repertoire
+          FAMILIARITY_BOOST = 0.2
+
+          # Boost from repeated observation of same behavior
+          REPETITION_BOOST = 0.1
+
+          # Maximum resonance value
+          MAX_RESONANCE = 1.0
+
+          # Imitation fidelity: how accurately behaviors are copied (0..1)
+          DEFAULT_FIDELITY = 0.7
+
+          # Fidelity improvement per successful imitation
+          FIDELITY_LEARNING_RATE = 0.05
+
+          # Maximum agents to mirror simultaneously
+          MAX_MIRRORED_AGENTS = 20
+
+          # Maximum behaviors in own repertoire
+          MAX_REPERTOIRE = 100
+
+          RESONANCE_LABELS = {
+            (0.8..)     => :strong_mirror,
+            (0.6...0.8) => :resonating,
+            (0.4...0.6) => :echoing,
+            (0.2...0.4) => :faint,
+            (..0.2)     => :silent
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mirror/helpers/mirror_system.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mirror
+      module Helpers
+        class MirrorSystem
+          include Constants
+
+          attr_reader :observations, :repertoire, :fidelity_scores, :imitation_history
+
+          def initialize
+            @observations     = {}
+            @repertoire       = {}
+            @fidelity_scores  = {}
+            @imitation_history = []
+          end
+
+          def observe(agent_id:, action:, domain:, context: nil, outcome: nil)
+            key = observation_key(agent_id, action, domain)
+            if @observations.key?(key)
+              @observations[key].observe_again
+              @observations[key]
+            else
+              ensure_observation_capacity
+              obs = ObservedBehavior.new(
+                agent_id: agent_id,
+                action:   action,
+                domain:   domain,
+                context:  context,
+                outcome:  outcome
+              )
+              obs.boost_familiarity if repertoire_includes?(action, domain)
+              @observations[key] = obs
+            end
+          end
+
+          def imitate(action:, domain:, source_agent: nil)
+            candidates = if source_agent
+                           observations_for_agent(source_agent).select { |o| o.action == action && o.domain == domain }
+                         else
+                           @observations.values.select { |o| o.action == action && o.domain == domain }
+                         end
+            return nil if candidates.empty?
+
+            best = candidates.max_by(&:resonance)
+            fidelity = fidelity_for(action, domain)
+            add_to_repertoire(action, domain, fidelity)
+            record_imitation(action, domain, source_agent, fidelity)
+            { observation: best, fidelity: fidelity }
+          end
+
+          def add_to_repertoire(action, domain, fidelity = DEFAULT_FIDELITY)
+            key = repertoire_key(action, domain)
+            if @repertoire.key?(key)
+              old = @repertoire[key][:fidelity]
+              @repertoire[key][:fidelity] = ema(old, fidelity, MIRROR_ALPHA)
+              @repertoire[key][:practice_count] += 1
+            else
+              trim_repertoire if @repertoire.size >= MAX_REPERTOIRE
+              @repertoire[key] = { action: action, domain: domain, fidelity: fidelity, practice_count: 1 }
+            end
+          end
+
+          def update_fidelity(action:, domain:, success:)
+            key = repertoire_key(action, domain)
+            @fidelity_scores[key] ||= DEFAULT_FIDELITY
+            delta = success ? FIDELITY_LEARNING_RATE : -FIDELITY_LEARNING_RATE
+            @fidelity_scores[key] = (@fidelity_scores[key] + delta).clamp(0.0, 1.0)
+          end
+
+          def fidelity_for(action, domain)
+            @fidelity_scores.fetch(repertoire_key(action, domain), DEFAULT_FIDELITY)
+          end
+
+          def observations_for_agent(agent_id)
+            @observations.values.select { |o| o.agent_id == agent_id }
+          end
+
+          def observations_in_domain(domain)
+            @observations.values.select { |o| o.domain == domain }
+          end
+
+          def strongest_mirrors(count = 5)
+            @observations.values.sort_by { |o| -o.resonance }.first(count)
+          end
+
+          def repertoire_includes?(action, domain)
+            @repertoire.key?(repertoire_key(action, domain))
+          end
+
+          def decay_all
+            @observations.each_value(&:decay)
+            @observations.reject! { |_, o| o.faded? }
+          end
+
+          def observation_count
+            @observations.size
+          end
+
+          def repertoire_size
+            @repertoire.size
+          end
+
+          def mirrored_agents
+            @observations.values.map(&:agent_id).uniq
+          end
+
+          def to_h
+            {
+              observations:    observation_count,
+              repertoire_size: repertoire_size,
+              mirrored_agents: mirrored_agents.size,
+              history_size:    @imitation_history.size
+            }
+          end
+
+          private
+
+          def observation_key(agent_id, action, domain)
+            :"#{agent_id}:#{action}:#{domain}"
+          end
+
+          def repertoire_key(action, domain)
+            :"#{action}:#{domain}"
+          end
+
+          def ema(old_val, new_val, alpha)
+            old_val + (alpha * (new_val - old_val))
+          end
+
+          def ensure_observation_capacity
+            return if @observations.size < MAX_OBSERVATIONS
+
+            weakest = @observations.min_by { |_, o| o.resonance }
+            @observations.delete(weakest.first) if weakest
+          end
+
+          def trim_repertoire
+            weakest = @repertoire.min_by { |_, r| r[:fidelity] }
+            @repertoire.delete(weakest.first) if weakest
+          end
+
+          def record_imitation(action, domain, source_agent, fidelity)
+            @imitation_history << {
+              action:       action,
+              domain:       domain,
+              source_agent: source_agent,
+              fidelity:     fidelity,
+              at:           Time.now.utc
+            }
+            @imitation_history.shift while @imitation_history.size > MAX_OBSERVATIONS
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mirror/helpers/observed_behavior.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mirror
+      module Helpers
+        class ObservedBehavior
+          attr_reader :id, :agent_id, :action, :domain, :context, :outcome, :created_at
+          attr_accessor :resonance, :observation_count
+
+          def initialize(agent_id:, action:, domain:, context: nil, outcome: nil, resonance: nil)
+            @id                = SecureRandom.uuid
+            @agent_id          = agent_id
+            @action            = action
+            @domain            = domain
+            @context           = context
+            @outcome           = outcome
+            @resonance         = (resonance || Constants::DEFAULT_RESONANCE).clamp(0.0, Constants::MAX_RESONANCE)
+            @observation_count = 1
+            @created_at        = Time.now.utc
+          end
+
+          def observe_again
+            @observation_count += 1
+            @resonance = [@resonance + Constants::REPETITION_BOOST, Constants::MAX_RESONANCE].min
+          end
+
+          def boost_familiarity
+            @resonance = [@resonance + Constants::FAMILIARITY_BOOST, Constants::MAX_RESONANCE].min
+          end
+
+          def decay
+            @resonance = [@resonance - Constants::RESONANCE_DECAY, Constants::RESONANCE_FLOOR].max
+          end
+
+          def faded?
+            @resonance <= Constants::RESONANCE_FLOOR
+          end
+
+          def label
+            Constants::RESONANCE_LABELS.each { |range, lbl| return lbl if range.cover?(@resonance) }
+            :silent
+          end
+
+          def to_h
+            {
+              id:                @id,
+              agent_id:          @agent_id,
+              action:            @action,
+              domain:            @domain,
+              context:           @context,
+              outcome:           @outcome,
+              resonance:         @resonance,
+              observation_count: @observation_count,
+              label:             label,
+              created_at:        @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mirror
+      module Runners
+        module Mirror
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def observe_behavior(agent_id:, action:, domain:, context: nil, outcome: nil, **)
+            obs = mirror_system.observe(agent_id: agent_id, action: action, domain: domain, context: context, outcome: outcome)
+            Legion::Logging.debug "[mirror] observe: agent=#{agent_id} action=#{action} domain=#{domain} " \
+                                  "resonance=#{obs.resonance.round(3)} count=#{obs.observation_count}"
+            { success: true, observation: obs.to_h }
+          end
+
+          def imitate_behavior(action:, domain:, source_agent: nil, **)
+            result = mirror_system.imitate(action: action, domain: domain, source_agent: source_agent)
+            if result
+              Legion::Logging.debug "[mirror] imitate: action=#{action} domain=#{domain} " \
+                                    "fidelity=#{result[:fidelity].round(3)}"
+              {
+                success:   true,
+                imitated:  true,
+                action:    action,
+                domain:    domain,
+                fidelity:  result[:fidelity].round(4),
+                source:    result[:observation].agent_id,
+                resonance: result[:observation].resonance.round(4)
+              }
+            else
+              Legion::Logging.debug "[mirror] imitate: action=#{action} domain=#{domain} no_observation"
+              { success: true, imitated: false, action: action, domain: domain }
+            end
+          end
+
+          def report_imitation_outcome(action:, domain:, success_flag:, **)
+            mirror_system.update_fidelity(action: action, domain: domain, success: success_flag)
+            fidelity = mirror_system.fidelity_for(action, domain)
+            Legion::Logging.debug "[mirror] outcome: action=#{action} domain=#{domain} " \
+                                  "success=#{success_flag} fidelity=#{fidelity.round(3)}"
+            { success: true, action: action, domain: domain, fidelity: fidelity.round(4) }
+          end
+
+          def strongest_mirrors(count: 5, **)
+            mirrors = mirror_system.strongest_mirrors(count)
+            Legion::Logging.debug "[mirror] strongest: count=#{mirrors.size}"
+            { success: true, mirrors: mirrors.map(&:to_h), count: mirrors.size }
+          end
+
+          def observations_for(agent_id:, **)
+            observations = mirror_system.observations_for_agent(agent_id)
+            Legion::Logging.debug "[mirror] observations_for: agent=#{agent_id} count=#{observations.size}"
+            { success: true, agent_id: agent_id, observations: observations.map(&:to_h), count: observations.size }
+          end
+
+          def observations_in(domain:, **)
+            observations = mirror_system.observations_in_domain(domain)
+            Legion::Logging.debug "[mirror] observations_in: domain=#{domain} count=#{observations.size}"
+            { success: true, domain: domain, observations: observations.map(&:to_h), count: observations.size }
+          end
+
+          def repertoire_status(**)
+            rep = mirror_system.repertoire
+            Legion::Logging.debug "[mirror] repertoire: size=#{rep.size}"
+            { success: true, repertoire: rep.values, size: rep.size }
+          end
+
+          def update_mirror(**)
+            mirror_system.decay_all
+            Legion::Logging.debug "[mirror] tick: observations=#{mirror_system.observation_count} " \
+                                  "repertoire=#{mirror_system.repertoire_size} agents=#{mirror_system.mirrored_agents.size}"
+            {
+              success:      true,
+              observations: mirror_system.observation_count,
+              repertoire:   mirror_system.repertoire_size,
+              agents:       mirror_system.mirrored_agents.size
+            }
+          end
+
+          def mirror_stats(**)
+            { success: true, stats: mirror_system.to_h }
+          end
+
+          private
+
+          def mirror_system
+            @mirror_system ||= Helpers::MirrorSystem.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/mirror.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/mirror/version'
+require 'legion/extensions/mirror/helpers/constants'
+require 'legion/extensions/mirror/helpers/observed_behavior'
+require 'legion/extensions/mirror/helpers/mirror_system'
+require 'legion/extensions/mirror/runners/mirror'
+require 'legion/extensions/mirror/client'
+
+module Legion
+  module Extensions
+    module Mirror
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Mirror::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes Runners::Mirror' do
+    expect(described_class.ancestors).to include(Legion::Extensions::Mirror::Runners::Mirror)
+  end
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:observe_behavior, :imitate_behavior, :report_imitation_outcome)
+    expect(client).to respond_to(:strongest_mirrors, :observations_for, :observations_in)
+    expect(client).to respond_to(:repertoire_status, :update_mirror, :mirror_stats)
+  end
+
+  it 'supports full mirror lifecycle' do
+    # Observe another agent deploying successfully
+    client.observe_behavior(agent_id: 'expert', action: :canary_deploy, domain: :production, outcome: :success)
+    client.observe_behavior(agent_id: 'expert', action: :canary_deploy, domain: :production, outcome: :success)
+
+    # Imitate the behavior
+    result = client.imitate_behavior(action: :canary_deploy, domain: :production)
+    expect(result[:imitated]).to be true
+    expect(result[:source]).to eq('expert')
+
+    # Report outcome
+    client.report_imitation_outcome(action: :canary_deploy, domain: :production, success_flag: true)
+
+    # Check repertoire
+    rep = client.repertoire_status
+    expect(rep[:size]).to eq(1)
+
+    # Tick
+    client.update_mirror
+
+    # Stats
+    stats = client.mirror_stats
+    expect(stats[:stats][:mirrored_agents]).to eq(1)
+  end
+end

data/spec/legion/extensions/mirror/helpers/mirror_system_spec.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Mirror::Helpers::MirrorSystem do
+  subject(:system) { described_class.new }
+
+  describe '#observe' do
+    it 'creates a new observation' do
+      obs = system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      expect(obs).to be_a(Legion::Extensions::Mirror::Helpers::ObservedBehavior)
+      expect(system.observation_count).to eq(1)
+    end
+
+    it 'increments count on repeated observation' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      obs = system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      expect(obs.observation_count).to eq(2)
+      expect(system.observation_count).to eq(1)
+    end
+
+    it 'boosts familiarity when behavior is in repertoire' do
+      system.add_to_repertoire(:deploy, :infra)
+      obs = system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      default = Legion::Extensions::Mirror::Helpers::Constants::DEFAULT_RESONANCE
+      boost = Legion::Extensions::Mirror::Helpers::Constants::FAMILIARITY_BOOST
+      expect(obs.resonance).to be_within(0.001).of(default + boost)
+    end
+
+    it 'tracks separate observations per agent' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      system.observe(agent_id: 'bob', action: :deploy, domain: :infra)
+      expect(system.observation_count).to eq(2)
+    end
+  end
+
+  describe '#imitate' do
+    it 'returns nil when no observations exist' do
+      expect(system.imitate(action: :deploy, domain: :infra)).to be_nil
+    end
+
+    it 'imitates observed behavior and adds to repertoire' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      result = system.imitate(action: :deploy, domain: :infra)
+      expect(result).not_to be_nil
+      expect(result[:observation].agent_id).to eq('alice')
+      expect(result[:fidelity]).to be_a(Float)
+      expect(system.repertoire_includes?(:deploy, :infra)).to be true
+    end
+
+    it 'filters by source_agent when specified' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      system.observe(agent_id: 'bob', action: :deploy, domain: :infra)
+      result = system.imitate(action: :deploy, domain: :infra, source_agent: 'alice')
+      expect(result[:observation].agent_id).to eq('alice')
+    end
+
+    it 'picks highest resonance observation' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      obs_bob = system.observe(agent_id: 'bob', action: :deploy, domain: :infra)
+      obs_bob.resonance = 0.9
+      result = system.imitate(action: :deploy, domain: :infra)
+      expect(result[:observation].agent_id).to eq('bob')
+    end
+  end
+
+  describe '#update_fidelity' do
+    it 'increases fidelity on success' do
+      before = system.fidelity_for(:deploy, :infra)
+      system.update_fidelity(action: :deploy, domain: :infra, success: true)
+      expect(system.fidelity_for(:deploy, :infra)).to be > before
+    end
+
+    it 'decreases fidelity on failure' do
+      before = system.fidelity_for(:deploy, :infra)
+      system.update_fidelity(action: :deploy, domain: :infra, success: false)
+      expect(system.fidelity_for(:deploy, :infra)).to be < before
+    end
+
+    it 'clamps to 0..1' do
+      20.times { system.update_fidelity(action: :deploy, domain: :infra, success: true) }
+      expect(system.fidelity_for(:deploy, :infra)).to be <= 1.0
+    end
+  end
+
+  describe '#observations_for_agent' do
+    it 'returns observations by specific agent' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      system.observe(agent_id: 'alice', action: :test, domain: :infra)
+      system.observe(agent_id: 'bob', action: :deploy, domain: :infra)
+      expect(system.observations_for_agent('alice').size).to eq(2)
+    end
+  end
+
+  describe '#observations_in_domain' do
+    it 'returns observations in domain' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      system.observe(agent_id: 'alice', action: :test, domain: :code)
+      expect(system.observations_in_domain(:infra).size).to eq(1)
+    end
+  end
+
+  describe '#strongest_mirrors' do
+    it 'returns top N by resonance' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      obs = system.observe(agent_id: 'bob', action: :test, domain: :code)
+      obs.resonance = 0.9
+      top = system.strongest_mirrors(1)
+      expect(top.size).to eq(1)
+      expect(top.first.agent_id).to eq('bob')
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all observations' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      before = system.observations.values.first.resonance
+      system.decay_all
+      after = system.observations.values.first&.resonance
+      expect(after).to be < before if after
+    end
+
+    it 'prunes faded observations' do
+      obs = system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      obs.resonance = Legion::Extensions::Mirror::Helpers::Constants::RESONANCE_FLOOR + 0.005
+      system.decay_all
+      expect(system.observation_count).to eq(0)
+    end
+  end
+
+  describe '#mirrored_agents' do
+    it 'lists unique observed agents' do
+      system.observe(agent_id: 'alice', action: :deploy, domain: :infra)
+      system.observe(agent_id: 'bob', action: :test, domain: :code)
+      system.observe(agent_id: 'alice', action: :test, domain: :code)
+      expect(system.mirrored_agents).to contain_exactly('alice', 'bob')
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash' do
+      h = system.to_h
+      expect(h).to include(:observations, :repertoire_size, :mirrored_agents, :history_size)
+    end
+  end
+end

data/spec/legion/extensions/mirror/helpers/observed_behavior_spec.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Mirror::Helpers::ObservedBehavior do
+  subject(:obs) { described_class.new(agent_id: 'alice', action: :deploy, domain: :infra) }
+
+  describe '#initialize' do
+    it 'assigns fields' do
+      expect(obs.agent_id).to eq('alice')
+      expect(obs.action).to eq(:deploy)
+      expect(obs.domain).to eq(:infra)
+      expect(obs.observation_count).to eq(1)
+    end
+
+    it 'assigns uuid and timestamp' do
+      expect(obs.id).to match(/\A[0-9a-f-]{36}\z/)
+      expect(obs.created_at).to be_a(Time)
+    end
+
+    it 'defaults resonance to DEFAULT_RESONANCE' do
+      expect(obs.resonance).to eq(Legion::Extensions::Mirror::Helpers::Constants::DEFAULT_RESONANCE)
+    end
+
+    it 'clamps resonance' do
+      high = described_class.new(agent_id: 'a', action: :x, domain: :d, resonance: 5.0)
+      expect(high.resonance).to eq(Legion::Extensions::Mirror::Helpers::Constants::MAX_RESONANCE)
+    end
+  end
+
+  describe '#observe_again' do
+    it 'increments observation count' do
+      obs.observe_again
+      expect(obs.observation_count).to eq(2)
+    end
+
+    it 'boosts resonance by REPETITION_BOOST' do
+      before = obs.resonance
+      obs.observe_again
+      expect(obs.resonance).to be > before
+    end
+  end
+
+  describe '#boost_familiarity' do
+    it 'boosts resonance by FAMILIARITY_BOOST' do
+      before = obs.resonance
+      obs.boost_familiarity
+      boost = Legion::Extensions::Mirror::Helpers::Constants::FAMILIARITY_BOOST
+      expect(obs.resonance).to be_within(0.001).of(before + boost)
+    end
+
+    it 'caps at MAX_RESONANCE' do
+      obs.resonance = 0.95
+      obs.boost_familiarity
+      expect(obs.resonance).to eq(Legion::Extensions::Mirror::Helpers::Constants::MAX_RESONANCE)
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces resonance' do
+      before = obs.resonance
+      obs.decay
+      expect(obs.resonance).to be < before
+    end
+
+    it 'does not drop below RESONANCE_FLOOR' do
+      50.times { obs.decay }
+      expect(obs.resonance).to be >= Legion::Extensions::Mirror::Helpers::Constants::RESONANCE_FLOOR
+    end
+  end
+
+  describe '#faded?' do
+    it 'returns false for strong observation' do
+      expect(obs.faded?).to be false
+    end
+
+    it 'returns true at floor' do
+      obs.resonance = Legion::Extensions::Mirror::Helpers::Constants::RESONANCE_FLOOR
+      expect(obs.faded?).to be true
+    end
+  end
+
+  describe '#label' do
+    it 'returns :faint for default resonance' do
+      expect(obs.label).to eq(:faint)
+    end
+
+    it 'returns :strong_mirror for high resonance' do
+      obs.resonance = 0.9
+      expect(obs.label).to eq(:strong_mirror)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash with all fields' do
+      h = obs.to_h
+      expect(h).to include(:id, :agent_id, :action, :domain, :resonance, :observation_count, :label, :created_at)
+    end
+  end
+end

data/spec/legion/extensions/mirror/runners/mirror_spec.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Mirror::Runners::Mirror do
+  let(:client) { Legion::Extensions::Mirror::Client.new }
+
+  describe '#observe_behavior' do
+    it 'creates an observation' do
+      result = client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      expect(result[:success]).to be true
+      expect(result[:observation][:agent_id]).to eq('alice')
+      expect(result[:observation][:action]).to eq(:deploy)
+    end
+
+    it 'boosts resonance on repeat observation' do
+      client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      result = client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      expect(result[:observation][:observation_count]).to eq(2)
+    end
+  end
+
+  describe '#imitate_behavior' do
+    it 'returns imitated: false with no observations' do
+      result = client.imitate_behavior(action: :deploy, domain: :infra)
+      expect(result[:success]).to be true
+      expect(result[:imitated]).to be false
+    end
+
+    it 'imitates observed behavior' do
+      client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      result = client.imitate_behavior(action: :deploy, domain: :infra)
+      expect(result[:imitated]).to be true
+      expect(result[:source]).to eq('alice')
+      expect(result[:fidelity]).to be_a(Float)
+    end
+
+    it 'filters by source_agent' do
+      client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      client.observe_behavior(agent_id: 'bob', action: :deploy, domain: :infra)
+      result = client.imitate_behavior(action: :deploy, domain: :infra, source_agent: 'bob')
+      expect(result[:source]).to eq('bob')
+    end
+  end
+
+  describe '#report_imitation_outcome' do
+    it 'updates fidelity on success' do
+      result = client.report_imitation_outcome(action: :deploy, domain: :infra, success_flag: true)
+      expect(result[:success]).to be true
+      expect(result[:fidelity]).to be > Legion::Extensions::Mirror::Helpers::Constants::DEFAULT_FIDELITY
+    end
+
+    it 'updates fidelity on failure' do
+      result = client.report_imitation_outcome(action: :deploy, domain: :infra, success_flag: false)
+      expect(result[:fidelity]).to be < Legion::Extensions::Mirror::Helpers::Constants::DEFAULT_FIDELITY
+    end
+  end
+
+  describe '#strongest_mirrors' do
+    it 'returns top mirrors' do
+      client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      client.observe_behavior(agent_id: 'bob', action: :test, domain: :code)
+      result = client.strongest_mirrors(count: 2)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#observations_for' do
+    it 'returns observations for agent' do
+      client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      client.observe_behavior(agent_id: 'alice', action: :test, domain: :code)
+      result = client.observations_for(agent_id: 'alice')
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'returns empty for unknown agent' do
+      result = client.observations_for(agent_id: 'nobody')
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#observations_in' do
+    it 'returns observations in domain' do
+      client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      client.observe_behavior(agent_id: 'bob', action: :test, domain: :code)
+      result = client.observations_in(domain: :infra)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#repertoire_status' do
+    it 'starts empty' do
+      result = client.repertoire_status
+      expect(result[:size]).to eq(0)
+    end
+
+    it 'grows after imitation' do
+      client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      client.imitate_behavior(action: :deploy, domain: :infra)
+      result = client.repertoire_status
+      expect(result[:size]).to eq(1)
+    end
+  end
+
+  describe '#update_mirror' do
+    it 'decays and returns stats' do
+      client.observe_behavior(agent_id: 'alice', action: :deploy, domain: :infra)
+      result = client.update_mirror
+      expect(result[:success]).to be true
+      expect(result).to have_key(:observations)
+      expect(result).to have_key(:repertoire)
+      expect(result).to have_key(:agents)
+    end
+  end
+
+  describe '#mirror_stats' do
+    it 'returns comprehensive stats' do
+      result = client.mirror_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:observations, :repertoire_size, :mirrored_agents)
+    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/mirror'
+
+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,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-mirror
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+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: Mirror neuron system for brain-modeled agentic AI — automatic behavioral
+  observation, imitation learning with fidelity tracking, and empathic resonance from
+  watching other agents act.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-mirror.gemspec
+- lib/legion/extensions/mirror.rb
+- lib/legion/extensions/mirror/actors/decay.rb
+- lib/legion/extensions/mirror/client.rb
+- lib/legion/extensions/mirror/helpers/constants.rb
+- lib/legion/extensions/mirror/helpers/mirror_system.rb
+- lib/legion/extensions/mirror/helpers/observed_behavior.rb
+- lib/legion/extensions/mirror/runners/mirror.rb
+- lib/legion/extensions/mirror/version.rb
+- spec/legion/extensions/mirror/client_spec.rb
+- spec/legion/extensions/mirror/helpers/mirror_system_spec.rb
+- spec/legion/extensions/mirror/helpers/observed_behavior_spec.rb
+- spec/legion/extensions/mirror/runners/mirror_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-mirror
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-mirror
+  source_code_uri: https://github.com/LegionIO/lex-mirror
+  documentation_uri: https://github.com/LegionIO/lex-mirror
+  changelog_uri: https://github.com/LegionIO/lex-mirror
+  bug_tracker_uri: https://github.com/LegionIO/lex-mirror/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 Mirror
+test_files: []