lex-cognitive-mirror 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a1a36459f44c549daf32dd96cdb4d65bf3d47819db378d55551686407f2da131
+  data.tar.gz: 34d942b917e9f0e32ff0a86e7eb1a69b0f68b2f6fbafa58c055690d176e23dc7
+SHA512:
+  metadata.gz: e26065baf0ebbd17ccf4d2ebe2f9369f5d0dd84f8ba3607692205b3e86770b0ba501a7a23234246194870c02d7b1771bcf53bb4b81c02c7ec926dda500c91aac
+  data.tar.gz: c84f0a5825e192a6d93abf60647c2f5621f71f786bacf5e0d0d77f61c2e83643476103266b0f2ebb524f987091d142d60098bc1d57d0864516b1c81b01d5c48c

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,44 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'

data/CLAUDE.md

@@ -0,0 +1,101 @@
+# lex-cognitive-mirror
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+
+## Purpose
+
+Theory of mind and empathic mirroring engine. Observes actions by other agents, simulates their likely intent, and tracks per-agent resonance scores (how aligned the agent is with the observer). Resonance boosts on each simulation and decays on each decay cycle. Accuracy tracking compares simulated outcomes against actual ones. Three separate runner modules split responsibilities: observation, simulation, and resonance management.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-mirror`
+- **Module**: `Legion::Extensions::CognitiveMirror`
+- **Version**: `0.1.0`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_mirror/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    mirror_engine.rb
+  runners/
+    observe.rb
+    simulate.rb
+    resonance.rb
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `MAX_EVENTS` | `500` | Observation event ring buffer capacity |
+| `MAX_SIMULATIONS` | `300` | Simulation record capacity |
+| `DEFAULT_RESONANCE` | `0.5` | Starting resonance for new agents |
+| `RESONANCE_BOOST` | `0.1` | Resonance increase per simulation |
+| `RESONANCE_DECAY` | `0.03` | Per-cycle resonance decay |
+| `ACTION_TYPES` | symbol array | Valid observable action types |
+| `RESONANCE_LABELS` | range hash | From `:estranged` to `:deeply_resonant` |
+| `CONFIDENCE_LABELS` | range hash | Simulation confidence labels |
+| `EMPATHY_LABELS` | range hash | Empathy level labels |
+
+## Helpers
+
+### `Helpers::MirrorEngine`
+Central engine with `INTENT_MAP` mapping action types to likely intents.
+
+- `observe(agent_id:, action_type:, content:, context:)` → event record; appended to ring buffer
+- `simulate(event_id:)` → derives outcome and intent via `INTENT_MAP`; boosts agent resonance by `RESONANCE_BOOST`
+- `record_accuracy(simulation_id:, actual_outcome:)` → accuracy record for the simulation
+- `empathic_resonance(agent_id:)` → current resonance float for agent
+- `boost_resonance(agent_id:, amount:)` → directly boost resonance
+- `decay_resonance(agent_id:)` → decay single agent's resonance by `RESONANCE_DECAY`
+- `decay_all_resonances` → decay all known agents
+- `simulation_accuracy_for(agent_id:)` → accuracy stats for agent
+- `events_for(agent_id:)` → all observation events for agent
+- `simulation_history(limit:)` → recent simulations
+- `known_agents` → list of agent IDs with resonance scores
+
+## Runners
+
+### `Runners::Observe`
+| Method | Description |
+|---|---|
+| `observe_action(agent_id:, action_type:, content:, context:)` | Record an observed action |
+| `list_events(agent_id:, limit:)` | Events for an agent |
+
+### `Runners::Simulate`
+| Method | Description |
+|---|---|
+| `simulate_action(event_id:)` | Simulate intent for an observed event |
+| `record_simulation_accuracy(simulation_id:, actual_outcome:)` | Record actual outcome vs simulated |
+| `simulation_history(limit:)` | Recent simulation records |
+
+### `Runners::Resonance`
+| Method | Description |
+|---|---|
+| `empathic_resonance(agent_id:)` | Current resonance for agent |
+| `decay_resonances(agent_id:)` | Decay one or all agent resonances |
+| `resonance_summary` | All agents and their resonance scores |
+
+All runners return `{success: true/false, ...}` hashes.
+
+## Integration Points
+
+- `lex-mesh`: mirror observations are naturally triggered by mesh message receipt — observe the sending agent's action
+- `lex-trust`: resonance scores complement trust scores; high resonance + high trust = most reliable agents
+- `lex-tick` `mesh_interface` phase: observe all incoming mesh messages before processing
+- `lex-identity`: behavioral fingerprint and empathic resonance are parallel models — fingerprint tracks the human partner, resonance tracks digital agents
+
+## Development Notes
+
+- `Client` includes all three runner modules (`Observe`, `Simulate`, `Resonance`)
+- `INTENT_MAP` is a static hash — intent inference is deterministic based on action type; no ML
+- Resonance is bounded [0.0, 1.0] via clamping in `boost_resonance` and `decay_resonance`
+- `MAX_EVENTS = 500` is a ring buffer; oldest events are dropped when full
+- Simulation accuracy requires a follow-up `record_accuracy` call from the caller after the actual outcome is known

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-mirror (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-mirror!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,51 @@
+# lex-cognitive-mirror
+
+Theory of mind and empathic mirroring for LegionIO cognitive agents. Observe other agents' actions, simulate their intent, track resonance scores, and measure simulation accuracy against actual outcomes.
+
+## What It Does
+
+- Observe actions from other agents (record into event ring buffer)
+- Simulate likely intent for observed events using an intent map
+- Each simulation boosts resonance with that agent
+- Resonance scores decay over time
+- Record actual outcomes to measure simulation accuracy
+- Track per-agent resonance, confidence, and empathy labels
+- Three focused runner modules: `Observe`, `Simulate`, `Resonance`
+
+## Usage
+
+```ruby
+# Observe an action
+runner.observe_action(agent_id: 'agent-123', action_type: :propose,
+                       content: 'suggesting a new approach', context: { domain: :architecture })
+# => { success: true, event_id: '...', agent_id: 'agent-123' }
+
+# Simulate intent for the event
+runner.simulate_action(event_id: event_id)
+# => { success: true, simulation_id: '...', simulated_intent: :collaboration, confidence: 0.7, ... }
+
+# Record actual outcome to track accuracy
+runner.record_simulation_accuracy(simulation_id: sim_id, actual_outcome: :collaboration)
+
+# Check resonance
+runner.empathic_resonance(agent_id: 'agent-123')
+# => { success: true, agent_id: 'agent-123', resonance: 0.6, label: :resonant }
+
+# Decay all resonances (call each tick)
+runner.decay_resonances(agent_id: nil)
+
+# Summary of all known agents
+runner.resonance_summary
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-mirror.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_mirror/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-mirror'
+  spec.version       = Legion::Extensions::CognitiveMirror::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'Mirror neuron simulation for LegionIO agents'
+  spec.description   = 'Mirror neuron simulation for LegionIO: observe, simulate, and build empathic resonance'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-mirror'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']          = spec.homepage
+  spec.metadata['source_code_uri']       = spec.homepage
+  spec.metadata['documentation_uri']     = "#{spec.homepage}/blob/main/README.md"
+  spec.metadata['changelog_uri']         = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['bug_tracker_uri']       = "#{spec.homepage}/issues"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_mirror/helpers/constants'
+require 'legion/extensions/cognitive_mirror/helpers/mirror_event'
+require 'legion/extensions/cognitive_mirror/helpers/simulation'
+require 'legion/extensions/cognitive_mirror/helpers/mirror_engine'
+require 'legion/extensions/cognitive_mirror/runners/observe'
+require 'legion/extensions/cognitive_mirror/runners/simulate'
+require 'legion/extensions/cognitive_mirror/runners/resonance'
+
+module Legion
+  module Extensions
+    module CognitiveMirror
+      class Client
+        include Runners::Observe
+        include Runners::Simulate
+        include Runners::Resonance
+
+        def initialize(**)
+          @mirror_engine = Helpers::MirrorEngine.new
+        end
+
+        private
+
+        attr_reader :mirror_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMirror
+      module Helpers
+        module Constants
+          MAX_EVENTS              = 500
+          MAX_SIMULATIONS         = 300
+          DEFAULT_RESONANCE       = 0.5
+          RESONANCE_BOOST         = 0.1
+          RESONANCE_DECAY         = 0.03
+          SIMULATION_CONFIDENCE_DEFAULT = 0.5
+
+          ACTION_TYPES = %i[
+            movement
+            communication
+            decision
+            emotional_expression
+            creative_act
+            analytical_task
+            social_interaction
+            unknown
+          ].freeze
+
+          RESONANCE_LABELS = {
+            (0.0..0.2) => :minimal,
+            (0.2..0.4) => :low,
+            (0.4..0.6) => :moderate,
+            (0.6..0.8) => :high,
+            (0.8..1.0) => :deep
+          }.freeze
+
+          CONFIDENCE_LABELS = {
+            (0.0..0.2) => :uncertain,
+            (0.2..0.4) => :tentative,
+            (0.4..0.6) => :plausible,
+            (0.6..0.8) => :confident,
+            (0.8..1.0) => :certain
+          }.freeze
+
+          EMPATHY_LABELS = {
+            (0.0..0.2) => :detached,
+            (0.2..0.4) => :aware,
+            (0.4..0.6) => :attuned,
+            (0.6..0.8) => :resonant,
+            (0.8..1.0) => :immersed
+          }.freeze
+
+          def self.label_for(labels_hash, value)
+            clamped = value.clamp(0.0, 1.0)
+            labels_hash.each do |range, label|
+              return label if range.cover?(clamped)
+            end
+            labels_hash.values.last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_mirror/helpers/mirror_engine.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMirror
+      module Helpers
+        class MirrorEngine
+          INTENT_MAP = {
+            communication:        :inform_or_persuade,
+            decision:             :resolve_uncertainty,
+            emotional_expression: :signal_internal_state,
+            creative_act:         :generate_novelty,
+            analytical_task:      :reduce_uncertainty,
+            social_interaction:   :build_relationship,
+            movement:             :change_position
+          }.freeze
+
+          attr_reader :events, :simulations, :resonance_map
+
+          def initialize
+            @events        = []
+            @simulations   = []
+            @resonance_map = Hash.new(Constants::DEFAULT_RESONANCE)
+          end
+
+          def observe(agent_id:, action_type:, context: {}, emotional_valence: 0.0)
+            event = MirrorEvent.new(
+              agent_id:          agent_id,
+              action_type:       action_type,
+              context:           context,
+              emotional_valence: emotional_valence
+            )
+            @events << event
+            @events.shift while @events.size > Constants::MAX_EVENTS
+            event
+          end
+
+          def simulate(event, confidence: Constants::SIMULATION_CONFIDENCE_DEFAULT)
+            resonance = compute_resonance_for(event)
+            outcome   = derive_outcome(event)
+
+            sim = Simulation.new(
+              event_id:            event.id,
+              simulated_outcome:   outcome,
+              confidence:          confidence,
+              emotional_resonance: resonance
+            )
+            @simulations << sim
+            @simulations.shift while @simulations.size > Constants::MAX_SIMULATIONS
+            sim
+          end
+
+          def record_accuracy(simulation_id, accuracy)
+            sim = @simulations.find { |s| s.id == simulation_id }
+            return false unless sim
+
+            sim.accuracy_score = accuracy.to_f.clamp(0.0, 1.0)
+            true
+          end
+
+          def empathic_resonance(agent_id)
+            @resonance_map[agent_id].clamp(0.0, 1.0)
+          end
+
+          def boost_resonance(agent_id)
+            current = @resonance_map[agent_id]
+            @resonance_map[agent_id] = (current + Constants::RESONANCE_BOOST).round(10).clamp(0.0, 1.0)
+          end
+
+          def decay_resonance(agent_id)
+            current = @resonance_map[agent_id]
+            @resonance_map[agent_id] = (current - Constants::RESONANCE_DECAY).round(10).clamp(0.0, 1.0)
+          end
+
+          def decay_all_resonances
+            @resonance_map.each_key { |agent_id| decay_resonance(agent_id) }
+          end
+
+          def simulation_accuracy_for(agent_id)
+            scored = simulations_for(agent_id).reject { |s| s.accuracy_score.nil? }
+            return nil if scored.empty?
+
+            scored.sum(&:accuracy_score) / scored.size.to_f
+          end
+
+          def simulations_for(agent_id)
+            event_ids = events_for(agent_id).map(&:id)
+            @simulations.select { |s| event_ids.include?(s.event_id) }
+          end
+
+          def events_for(agent_id)
+            @events.select { |e| e.agent_id == agent_id }
+          end
+
+          def simulation_history(limit: 20)
+            @simulations.last(limit).map(&:to_h)
+          end
+
+          def known_agents
+            @resonance_map.keys
+          end
+
+          private
+
+          def compute_resonance_for(event)
+            base      = @resonance_map[event.agent_id]
+            valence   = event.emotional_valence.abs
+            resonance = (base + (valence * Constants::RESONANCE_BOOST)).round(10)
+            resonance.clamp(0.0, 1.0)
+          end
+
+          def derive_outcome(event)
+            {
+              action_type:      event.action_type,
+              predicted_intent: infer_intent(event),
+              emotional_echo:   event.emotional_valence,
+              context_keys:     event.context.keys
+            }
+          end
+
+          def infer_intent(event)
+            INTENT_MAP.fetch(event.action_type, :unknown_intent)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_mirror/helpers/mirror_event.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveMirror
+      module Helpers
+        class MirrorEvent
+          attr_reader :id, :agent_id, :action_type, :context, :emotional_valence, :observed_at
+
+          def initialize(agent_id:, action_type:, context: {}, emotional_valence: 0.0)
+            @id               = SecureRandom.uuid
+            @agent_id         = agent_id
+            @action_type      = normalize_action_type(action_type)
+            @context          = context.is_a?(Hash) ? context : {}
+            @emotional_valence = emotional_valence.to_f.clamp(-1.0, 1.0)
+            @observed_at = Time.now.utc
+          end
+
+          def to_h
+            {
+              id:                @id,
+              agent_id:          @agent_id,
+              action_type:       @action_type,
+              context:           @context,
+              emotional_valence: @emotional_valence,
+              observed_at:       @observed_at
+            }
+          end
+
+          private
+
+          def normalize_action_type(action_type)
+            sym = action_type.to_sym
+            Constants::ACTION_TYPES.include?(sym) ? sym : :unknown
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_mirror/helpers/simulation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveMirror
+      module Helpers
+        class Simulation
+          attr_reader :id, :event_id, :simulated_outcome, :confidence, :emotional_resonance, :simulated_at
+          attr_accessor :accuracy_score
+
+          def initialize(event_id:, simulated_outcome:, confidence: Constants::SIMULATION_CONFIDENCE_DEFAULT,
+                         emotional_resonance: Constants::DEFAULT_RESONANCE)
+            @id                  = SecureRandom.uuid
+            @event_id            = event_id
+            @simulated_outcome   = simulated_outcome
+            @confidence          = confidence.to_f.clamp(0.0, 1.0)
+            @emotional_resonance = emotional_resonance.to_f.clamp(0.0, 1.0)
+            @simulated_at        = Time.now.utc
+            @accuracy_score      = nil
+          end
+
+          def to_h
+            {
+              id:                  @id,
+              event_id:            @event_id,
+              simulated_outcome:   @simulated_outcome,
+              confidence:          @confidence,
+              emotional_resonance: @emotional_resonance,
+              simulated_at:        @simulated_at,
+              accuracy_score:      @accuracy_score
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_mirror/runners/observe.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMirror
+      module Runners
+        module Observe
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def observe_action(agent_id:, action_type:, context: {}, emotional_valence: 0.0, engine: nil, **)
+            eng = engine || mirror_engine
+
+            unless Helpers::Constants::ACTION_TYPES.include?(action_type.to_sym)
+              Legion::Logging.debug "[cognitive_mirror] unknown action_type=#{action_type}, mapping to :unknown"
+            end
+
+            event = eng.observe(
+              agent_id:          agent_id,
+              action_type:       action_type,
+              context:           context,
+              emotional_valence: emotional_valence
+            )
+
+            resonance_label = Helpers::Constants.label_for(Helpers::Constants::RESONANCE_LABELS,
+                                                           eng.empathic_resonance(agent_id))
+            Legion::Logging.debug "[cognitive_mirror] observed action=#{event.action_type} " \
+                                  "agent=#{agent_id} resonance_tier=#{resonance_label}"
+
+            { success: true, event: event.to_h, resonance_tier: resonance_label }
+          end
+
+          def list_events(agent_id: nil, engine: nil, **)
+            eng = engine || mirror_engine
+            events = agent_id ? eng.events_for(agent_id) : eng.events
+            { success: true, events: events.map(&:to_h), count: events.size }
+          end
+
+          private
+
+          def mirror_engine
+            @mirror_engine ||= Helpers::MirrorEngine.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_mirror/runners/resonance.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMirror
+      module Runners
+        module Resonance
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def empathic_resonance(agent_id:, engine: nil, **)
+            eng = engine || mirror_engine
+            value = eng.empathic_resonance(agent_id)
+            accuracy = eng.simulation_accuracy_for(agent_id)
+
+            empathy_label   = Helpers::Constants.label_for(Helpers::Constants::EMPATHY_LABELS, value)
+            resonance_label = Helpers::Constants.label_for(Helpers::Constants::RESONANCE_LABELS, value)
+
+            Legion::Logging.debug "[cognitive_mirror] resonance agent=#{agent_id} " \
+                                  "value=#{value.round(3)} empathy=#{empathy_label}"
+
+            {
+              success:          true,
+              agent_id:         agent_id,
+              resonance:        value,
+              resonance_label:  resonance_label,
+              empathy_label:    empathy_label,
+              accuracy:         accuracy,
+              event_count:      eng.events_for(agent_id).size,
+              simulation_count: eng.simulations_for(agent_id).size
+            }
+          end
+
+          def decay_resonances(agent_id: nil, engine: nil, **)
+            eng = engine || mirror_engine
+
+            if agent_id
+              eng.decay_resonance(agent_id)
+              after = eng.empathic_resonance(agent_id)
+              Legion::Logging.debug "[cognitive_mirror] resonance decayed agent=#{agent_id} after=#{after.round(3)}"
+              { success: true, agent_id: agent_id, resonance_after: after }
+            else
+              eng.decay_all_resonances
+              summary = eng.known_agents.to_h { |id| [id, eng.empathic_resonance(id)] }
+              Legion::Logging.debug "[cognitive_mirror] global resonance decay agents=#{summary.size}"
+              { success: true, agents_decayed: summary.size, resonances: summary }
+            end
+          end
+
+          def resonance_summary(engine: nil, **)
+            eng = engine || mirror_engine
+            agents = eng.known_agents
+
+            summary = agents.map do |id|
+              value = eng.empathic_resonance(id)
+              {
+                agent_id:      id,
+                resonance:     value,
+                empathy_label: Helpers::Constants.label_for(Helpers::Constants::EMPATHY_LABELS, value)
+              }
+            end
+
+            { success: true, agents: summary, total: agents.size }
+          end
+
+          private
+
+          def mirror_engine
+            @mirror_engine ||= Helpers::MirrorEngine.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_mirror/runners/simulate.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMirror
+      module Runners
+        module Simulate
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def simulate_action(event_id:, confidence: Helpers::Constants::SIMULATION_CONFIDENCE_DEFAULT,
+                              engine: nil, **)
+            eng = engine || mirror_engine
+
+            event = eng.events.find { |e| e.id == event_id }
+            unless event
+              Legion::Logging.debug "[cognitive_mirror] simulate_action: event_id=#{event_id} not found"
+              return { success: false, error: 'event not found', event_id: event_id }
+            end
+
+            sim = eng.simulate(event, confidence: confidence)
+            eng.boost_resonance(event.agent_id)
+
+            confidence_label = Helpers::Constants.label_for(Helpers::Constants::CONFIDENCE_LABELS, sim.confidence)
+            Legion::Logging.debug "[cognitive_mirror] simulated event=#{event_id} " \
+                                  "confidence_tier=#{confidence_label} resonance=#{sim.emotional_resonance.round(3)}"
+
+            { success: true, simulation: sim.to_h, confidence_tier: confidence_label }
+          end
+
+          def record_simulation_accuracy(simulation_id:, accuracy:, engine: nil, **)
+            eng = engine || mirror_engine
+            recorded = eng.record_accuracy(simulation_id, accuracy)
+
+            unless recorded
+              Legion::Logging.debug "[cognitive_mirror] record_accuracy: simulation_id=#{simulation_id} not found"
+              return { success: false, error: 'simulation not found', simulation_id: simulation_id }
+            end
+
+            Legion::Logging.debug "[cognitive_mirror] accuracy recorded simulation=#{simulation_id} score=#{accuracy}"
+            { success: true, simulation_id: simulation_id, accuracy: accuracy.to_f.clamp(0.0, 1.0) }
+          end
+
+          def simulation_history(limit: 20, engine: nil, **)
+            eng = engine || mirror_engine
+            history = eng.simulation_history(limit: limit)
+            { success: true, simulations: history, count: history.size }
+          end
+
+          private
+
+          def mirror_engine
+            @mirror_engine ||= Helpers::MirrorEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_mirror.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_mirror/version'
+require 'legion/extensions/cognitive_mirror/helpers/constants'
+require 'legion/extensions/cognitive_mirror/helpers/mirror_event'
+require 'legion/extensions/cognitive_mirror/helpers/simulation'
+require 'legion/extensions/cognitive_mirror/helpers/mirror_engine'
+require 'legion/extensions/cognitive_mirror/runners/observe'
+require 'legion/extensions/cognitive_mirror/runners/simulate'
+require 'legion/extensions/cognitive_mirror/runners/resonance'
+require 'legion/extensions/cognitive_mirror/client'
+
+module Legion
+  module Extensions
+    module CognitiveMirror
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-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 simulation for LegionIO: observe, simulate, and build
+  empathic resonance'
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- lex-cognitive-mirror.gemspec
+- lib/legion/extensions/cognitive_mirror.rb
+- lib/legion/extensions/cognitive_mirror/client.rb
+- lib/legion/extensions/cognitive_mirror/helpers/constants.rb
+- lib/legion/extensions/cognitive_mirror/helpers/mirror_engine.rb
+- lib/legion/extensions/cognitive_mirror/helpers/mirror_event.rb
+- lib/legion/extensions/cognitive_mirror/helpers/simulation.rb
+- lib/legion/extensions/cognitive_mirror/runners/observe.rb
+- lib/legion/extensions/cognitive_mirror/runners/resonance.rb
+- lib/legion/extensions/cognitive_mirror/runners/simulate.rb
+- lib/legion/extensions/cognitive_mirror/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-mirror
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-mirror
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-mirror
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-mirror/blob/main/README.md
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-mirror/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-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: Mirror neuron simulation for LegionIO agents
+test_files: []