lex-conflict 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65f2f15e0488f24bca7c7c48246a8bc580907a00c182d79a8ae0ab37b5f71dd8
+  data.tar.gz: 8e104dc880a3d63fa9a4484b6d191e585db5beffea4187708cd4fd5f9724b8f2
+SHA512:
+  metadata.gz: 8444218ce37f8cf5108e6eb9783dcad8a48f02971ed2ede1718e405712e9448998ee128b198fac613e3dafc56f67a941248de16819b8ec665996bc822c8582c3
+  data.tar.gz: ea7cd9b0ef64a4ee8e4eaaef37414a455e503676653524798cb5b1a90ccb796ec0cba9d563ba0000268680169b3943022c949523fea850cf993445bdfcd283ea

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-conflict.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/conflict/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-conflict'
+  spec.version       = Legion::Extensions::Conflict::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Conflict'
+  spec.description   = 'Conflict resolution with severity levels and postures for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-conflict'
+  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-conflict'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-conflict'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-conflict'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-conflict/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-conflict.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/conflict/actors/stale_check.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Conflict
+      module Actor
+        class StaleCheck < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Conflict::Runners::Conflict
+          end
+
+          def runner_function
+            'check_stale_conflicts'
+          end
+
+          def time
+            3600
+          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/conflict/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/conflict/helpers/severity'
+require 'legion/extensions/conflict/helpers/conflict_log'
+require 'legion/extensions/conflict/runners/conflict'
+
+module Legion
+  module Extensions
+    module Conflict
+      class Client
+        include Runners::Conflict
+
+        def initialize(**)
+          @conflict_log = Helpers::ConflictLog.new
+        end
+
+        private
+
+        attr_reader :conflict_log
+      end
+    end
+  end
+end

data/lib/legion/extensions/conflict/helpers/conflict_log.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Conflict
+      module Helpers
+        class ConflictLog
+          attr_reader :conflicts
+
+          def initialize
+            @conflicts = {}
+          end
+
+          def record(parties:, severity:, description:, posture: nil)
+            id = SecureRandom.uuid
+            @conflicts[id] = {
+              conflict_id: id,
+              parties:     parties,
+              severity:    severity,
+              posture:     posture || Severity.recommended_posture(severity),
+              description: description,
+              status:      :active,
+              outcome:     nil,
+              created_at:  Time.now.utc,
+              resolved_at: nil,
+              exchanges:   []
+            }
+            id
+          end
+
+          def add_exchange(conflict_id, speaker:, message:)
+            conflict = @conflicts[conflict_id]
+            return nil unless conflict
+
+            conflict[:exchanges] << { speaker: speaker, message: message, at: Time.now.utc }
+          end
+
+          def resolve(conflict_id, outcome:, resolution_notes: nil)
+            conflict = @conflicts[conflict_id]
+            return nil unless conflict
+
+            conflict[:status] = :resolved
+            conflict[:outcome] = outcome
+            conflict[:resolution_notes] = resolution_notes
+            conflict[:resolved_at] = Time.now.utc
+            conflict
+          end
+
+          def active_conflicts
+            @conflicts.values.select { |c| c[:status] == :active }
+          end
+
+          def get(conflict_id)
+            @conflicts[conflict_id]
+          end
+
+          def count
+            @conflicts.size
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/conflict/helpers/llm_enhancer.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Conflict
+      module Helpers
+        module LlmEnhancer
+          SYSTEM_PROMPT = <<~PROMPT
+            You are the conflict mediation processor for an autonomous AI agent built on LegionIO.
+            You analyze disagreements between the agent and human partners, then suggest resolution approaches.
+            Be neutral, constructive, and specific. Focus on finding common ground and actionable next steps.
+            Do not take sides. Identify the underlying needs behind each position.
+          PROMPT
+
+          module_function
+
+          def available?
+            defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?
+          rescue StandardError
+            false
+          end
+
+          def suggest_resolution(description:, severity:, exchanges:)
+            prompt = build_suggest_resolution_prompt(description: description, severity: severity, exchanges: exchanges)
+            response = llm_ask(prompt)
+            parse_suggest_resolution_response(response)
+          rescue StandardError => e
+            Legion::Logging.warn "[conflict:llm] suggest_resolution failed: #{e.message}"
+            nil
+          end
+
+          def analyze_stale_conflict(description:, severity:, age_hours:, exchange_count:)
+            prompt = build_analyze_stale_conflict_prompt(
+              description:    description,
+              severity:       severity,
+              age_hours:      age_hours,
+              exchange_count: exchange_count
+            )
+            response = llm_ask(prompt)
+            parse_analyze_stale_conflict_response(response)
+          rescue StandardError => e
+            Legion::Logging.warn "[conflict:llm] analyze_stale_conflict failed: #{e.message}"
+            nil
+          end
+
+          # --- Private helpers ---
+
+          def llm_ask(prompt)
+            chat = Legion::LLM.chat
+            chat.with_instructions(SYSTEM_PROMPT)
+            chat.ask(prompt)
+          end
+          private_class_method :llm_ask
+
+          def build_suggest_resolution_prompt(description:, severity:, exchanges:)
+            exchange_lines = exchanges.map { |e| "[#{e[:speaker]}]: #{e[:message]}" }.join("\n")
+
+            <<~PROMPT
+              Analyze this conflict and suggest a resolution.
+
+              DESCRIPTION: #{description}
+              SEVERITY: #{severity}
+              EXCHANGE HISTORY (#{exchanges.size} exchanges):
+              #{exchange_lines}
+
+              Suggest a constructive resolution approach.
+
+              Format EXACTLY as:
+              OUTCOME: resolved | deferred | escalated
+              NOTES: <2-3 sentences describing the resolution approach and next steps>
+            PROMPT
+          end
+          private_class_method :build_suggest_resolution_prompt
+
+          def parse_suggest_resolution_response(response)
+            return nil unless response&.content
+
+            text = response.content
+            outcome_match = text.match(/OUTCOME:\s*(resolved|deferred|escalated)/i)
+            notes_match   = text.match(/NOTES:\s*(.+)/im)
+
+            return nil unless outcome_match && notes_match
+
+            outcome = outcome_match.captures.first.strip.downcase.to_sym
+            notes   = notes_match.captures.first.strip
+
+            { resolution_notes: notes, suggested_outcome: outcome }
+          end
+          private_class_method :parse_suggest_resolution_response
+
+          def build_analyze_stale_conflict_prompt(description:, severity:, age_hours:, exchange_count:)
+            <<~PROMPT
+              A conflict has been unresolved for #{age_hours.round(1)} hours with #{exchange_count} exchanges.
+
+              DESCRIPTION: #{description}
+              SEVERITY: #{severity}
+
+              Recommend how to proceed with this stale conflict.
+
+              Format EXACTLY as:
+              RECOMMENDATION: escalate | retry | close
+              ANALYSIS: <2-3 sentences explaining the recommendation>
+            PROMPT
+          end
+          private_class_method :build_analyze_stale_conflict_prompt
+
+          def parse_analyze_stale_conflict_response(response)
+            return nil unless response&.content
+
+            text = response.content
+            rec_match      = text.match(/RECOMMENDATION:\s*(escalate|retry|close)/i)
+            analysis_match = text.match(/ANALYSIS:\s*(.+)/im)
+
+            return nil unless rec_match && analysis_match
+
+            recommendation = rec_match.captures.first.strip.downcase.to_sym
+            analysis       = analysis_match.captures.first.strip
+
+            { analysis: analysis, recommendation: recommendation }
+          end
+          private_class_method :parse_analyze_stale_conflict_response
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/conflict/helpers/severity.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Conflict
+      module Helpers
+        module Severity
+          LEVELS = %i[low medium high critical].freeze
+          POSTURES = %i[speak_once persistent_engagement stubborn_presence].freeze
+
+          # Posture selection thresholds
+          PERSISTENT_THRESHOLD = :high
+          STUBBORN_THRESHOLD   = :critical
+
+          LEVEL_ORDER             = { low: 0, medium: 1, high: 2, critical: 3 }.freeze
+          STALE_CONFLICT_TIMEOUT  = 86_400 # 24 hours
+
+          module_function
+
+          def valid_level?(level)
+            LEVELS.include?(level)
+          end
+
+          def valid_posture?(posture)
+            POSTURES.include?(posture)
+          end
+
+          def recommended_posture(severity)
+            case severity
+            when :critical then :stubborn_presence
+            when :high     then :persistent_engagement
+            else :speak_once
+            end
+          end
+
+          def severity_gte?(left, right)
+            LEVEL_ORDER.fetch(left, 0) >= LEVEL_ORDER.fetch(right, 0)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Conflict
+      module Runners
+        module Conflict
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_conflict(parties:, severity:, description:, **)
+            return { error: :invalid_severity, valid: Helpers::Severity::LEVELS } unless Helpers::Severity.valid_level?(severity)
+
+            id = conflict_log.record(parties: parties, severity: severity, description: description)
+            conflict = conflict_log.get(id)
+            Legion::Logging.info "[conflict] registered: id=#{id[0..7]} severity=#{severity} posture=#{conflict[:posture]} parties=#{parties.join(',')}"
+            { conflict_id: id, severity: severity, posture: conflict[:posture] }
+          end
+
+          def add_exchange(conflict_id:, speaker:, message:, **)
+            result = conflict_log.add_exchange(conflict_id, speaker: speaker, message: message)
+            if result
+              Legion::Logging.debug "[conflict] exchange: id=#{conflict_id[0..7]} speaker=#{speaker}"
+              { recorded: true }
+            else
+              Legion::Logging.debug "[conflict] exchange failed: id=#{conflict_id[0..7]} not found"
+              { error: :not_found }
+            end
+          end
+
+          def resolve_conflict(conflict_id:, outcome:, resolution_notes: nil, **)
+            conflict = conflict_log.get(conflict_id)
+            unless conflict
+              Legion::Logging.debug "[conflict] resolve failed: id=#{conflict_id[0..7]} not found"
+              return { error: :not_found }
+            end
+
+            if resolution_notes.nil? && Helpers::LlmEnhancer.available?
+              llm_result = Helpers::LlmEnhancer.suggest_resolution(
+                description: conflict[:description],
+                severity:    conflict[:severity],
+                exchanges:   conflict[:exchanges]
+              )
+              resolution_notes = llm_result[:resolution_notes] if llm_result
+            end
+
+            result = conflict_log.resolve(conflict_id, outcome: outcome, resolution_notes: resolution_notes)
+            if result
+              Legion::Logging.info "[conflict] resolved: id=#{conflict_id[0..7]} outcome=#{outcome}"
+              { resolved: true, outcome: outcome }
+            else
+              Legion::Logging.debug "[conflict] resolve failed: id=#{conflict_id[0..7]} not found"
+              { error: :not_found }
+            end
+          end
+
+          def get_conflict(conflict_id:, **)
+            conflict = conflict_log.get(conflict_id)
+            Legion::Logging.debug "[conflict] get: id=#{conflict_id[0..7]} found=#{!conflict.nil?}"
+            conflict ? { found: true, conflict: conflict } : { found: false }
+          end
+
+          def active_conflicts(**)
+            conflicts = conflict_log.active_conflicts
+            Legion::Logging.debug "[conflict] active: count=#{conflicts.size}"
+            { conflicts: conflicts, count: conflicts.size }
+          end
+
+          def check_stale_conflicts(**)
+            active = conflict_log.active_conflicts
+            stale  = active.select { |c| Time.now.utc - c[:created_at] > Helpers::Severity::STALE_CONFLICT_TIMEOUT }
+            stale.each do |c|
+              message = 'conflict marked stale — no resolution after 24h'
+
+              if Helpers::LlmEnhancer.available?
+                age_hours = (Time.now.utc - c[:created_at]) / 3600.0
+                analysis  = Helpers::LlmEnhancer.analyze_stale_conflict(
+                  description:    c[:description],
+                  severity:       c[:severity],
+                  age_hours:      age_hours,
+                  exchange_count: c[:exchanges].size
+                )
+                message = "conflict marked stale — #{analysis[:analysis]} (recommendation: #{analysis[:recommendation]})" if analysis
+              end
+
+              conflict_log.add_exchange(c[:conflict_id], speaker: :system, message: message)
+            end
+            stale_ids = stale.map { |c| c[:conflict_id] }
+            Legion::Logging.debug "[conflict] stale check: active=#{active.size} stale=#{stale.size}"
+            { checked: active.size, stale_count: stale.size, stale_ids: stale_ids }
+          end
+
+          def recommended_posture(severity:, **)
+            posture = Helpers::Severity.recommended_posture(severity)
+            Legion::Logging.debug "[conflict] posture: severity=#{severity} posture=#{posture}"
+            { severity: severity, posture: posture }
+          end
+
+          private
+
+          def conflict_log
+            @conflict_log ||= Helpers::ConflictLog.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/conflict.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/conflict/version'
+require 'legion/extensions/conflict/helpers/severity'
+require 'legion/extensions/conflict/helpers/conflict_log'
+require 'legion/extensions/conflict/helpers/llm_enhancer'
+require 'legion/extensions/conflict/runners/conflict'
+
+module Legion
+  module Extensions
+    module Conflict
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/conflict/actors/stale_check_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Actors
+      class Every; end # rubocop:disable Lint/EmptyClass
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/conflict/actors/stale_check'
+
+RSpec.describe Legion::Extensions::Conflict::Actor::StaleCheck do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it { expect(actor.runner_class).to eq Legion::Extensions::Conflict::Runners::Conflict }
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'check_stale_conflicts' }
+  end
+
+  describe '#time' do
+    it { expect(actor.time).to eq 3600 }
+  end
+
+  describe '#run_now?' do
+    it { expect(actor.run_now?).to be false }
+  end
+
+  describe '#use_runner?' do
+    it { expect(actor.use_runner?).to be false }
+  end
+
+  describe '#check_subtask?' do
+    it { expect(actor.check_subtask?).to be false }
+  end
+
+  describe '#generate_task?' do
+    it { expect(actor.generate_task?).to be false }
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/conflict/client'
+
+RSpec.describe Legion::Extensions::Conflict::Client do
+  it 'responds to conflict runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:register_conflict)
+    expect(client).to respond_to(:add_exchange)
+    expect(client).to respond_to(:resolve_conflict)
+    expect(client).to respond_to(:get_conflict)
+    expect(client).to respond_to(:active_conflicts)
+    expect(client).to respond_to(:recommended_posture)
+  end
+end