lex-agentic-social 0.1.0

data/lib/legion/extensions/agentic/social/governance/actors/vote_timeout.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Governance
+          module Actor
+            class VoteTimeout < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Social::Governance::Runners::Governance
+              end
+
+              def runner_function
+                'timeout_proposals'
+              end
+
+              def time
+                300
+              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
+  end
+end

data/lib/legion/extensions/agentic/social/governance/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/governance/helpers/layers'
+require 'legion/extensions/agentic/social/governance/helpers/proposal'
+require 'legion/extensions/agentic/social/governance/runners/governance'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Governance
+          class Client
+            include Runners::Governance
+
+            def initialize(**)
+              @proposal_store = Helpers::Proposal.new
+            end
+
+            private
+
+            attr_reader :proposal_store
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/governance/helpers/layers.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Governance
+          module Helpers
+            module Layers
+              # Four governance layers (spec: governance-protocol-spec.md)
+              GOVERNANCE_LAYERS = %i[agent_validation anomaly_detection human_deliberation transparency].freeze
+
+              # Council quorum requirements
+              MIN_COUNCIL_SIZE    = 3
+              QUORUM_FRACTION     = 0.66
+              VOTE_TIMEOUT        = 86_400 # 24 hours
+              PROPOSAL_CATEGORIES = %i[policy_change resource_allocation access_control emergency protocol_update].freeze
+
+              module_function
+
+              def valid_layer?(layer)
+                GOVERNANCE_LAYERS.include?(layer)
+              end
+
+              def valid_category?(category)
+                PROPOSAL_CATEGORIES.include?(category)
+              end
+
+              def quorum_met?(votes, council_size)
+                return false if council_size < MIN_COUNCIL_SIZE
+
+                votes >= (council_size * QUORUM_FRACTION).ceil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/governance/helpers/proposal.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Governance
+          module Helpers
+            class Proposal
+              attr_reader :proposals
+
+              def initialize
+                @proposals = {}
+              end
+
+              def create(category:, description:, proposer:, council_size: Layers::MIN_COUNCIL_SIZE)
+                id = SecureRandom.uuid
+                @proposals[id] = {
+                  proposal_id:   id,
+                  category:      category,
+                  description:   description,
+                  proposer:      proposer,
+                  council_size:  council_size,
+                  votes_for:     [],
+                  votes_against: [],
+                  status:        :open,
+                  created_at:    Time.now.utc,
+                  resolved_at:   nil
+                }
+                id
+              end
+
+              def vote(proposal_id, voter:, approve:)
+                prop = @proposals[proposal_id]
+                return nil unless prop && prop[:status] == :open
+
+                # Prevent double-voting
+                all_voters = prop[:votes_for] + prop[:votes_against]
+                return :already_voted if all_voters.include?(voter)
+
+                if approve
+                  prop[:votes_for] << voter
+                else
+                  prop[:votes_against] << voter
+                end
+
+                check_resolution(proposal_id)
+              end
+
+              def get(proposal_id)
+                @proposals[proposal_id]
+              end
+
+              def open_proposals
+                @proposals.values.select { |p| p[:status] == :open }
+              end
+
+              def resolve_timed_out(proposal_id)
+                prop = @proposals[proposal_id]
+                return nil unless prop && prop[:status] == :open
+
+                prop[:status]      = :timed_out
+                prop[:resolved_at] = Time.now.utc
+                prop
+              end
+
+              private
+
+              def check_resolution(proposal_id)
+                prop = @proposals[proposal_id]
+                total_votes = prop[:votes_for].size + prop[:votes_against].size
+
+                if Layers.quorum_met?(prop[:votes_for].size, prop[:council_size])
+                  prop[:status] = :approved
+                  prop[:resolved_at] = Time.now.utc
+                  :approved
+                elsif Layers.quorum_met?(prop[:votes_against].size, prop[:council_size]) ||
+                      total_votes >= prop[:council_size]
+                  prop[:status] = :rejected
+                  prop[:resolved_at] = Time.now.utc
+                  :rejected
+                else
+                  :pending
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/governance/runners/governance.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Governance
+          module Runners
+            module Governance
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_proposal(category:, description:, proposer:, council_size: nil, **)
+                return { error: :invalid_category, valid: Helpers::Layers::PROPOSAL_CATEGORIES } unless Helpers::Layers.valid_category?(category)
+
+                size = council_size || Helpers::Layers::MIN_COUNCIL_SIZE
+                id = proposal_store.create(category: category, description: description,
+                                           proposer: proposer, council_size: size)
+                Legion::Logging.info "[governance] proposal created: id=#{id[0..7]} category=#{category} proposer=#{proposer} council=#{size}"
+                { proposal_id: id, category: category, status: :open }
+              end
+
+              def vote_on_proposal(proposal_id:, voter:, approve:, **)
+                result = proposal_store.vote(proposal_id, voter: voter, approve: approve)
+                case result
+                when nil
+                  Legion::Logging.debug "[governance] vote failed: proposal=#{proposal_id[0..7]} not found or closed"
+                  { error: :not_found_or_closed }
+                when :already_voted
+                  Legion::Logging.debug "[governance] vote failed: proposal=#{proposal_id[0..7]} voter=#{voter} already voted"
+                  { error: :already_voted }
+                else
+                  Legion::Logging.info "[governance] vote: proposal=#{proposal_id[0..7]} voter=#{voter} approve=#{approve} resolution=#{result}"
+                  { voted: true, resolution: result }
+                end
+              end
+
+              def get_proposal(proposal_id:, **)
+                prop = proposal_store.get(proposal_id)
+                Legion::Logging.debug "[governance] get: proposal=#{proposal_id[0..7]} found=#{!prop.nil?}"
+                prop ? { found: true, proposal: prop } : { found: false }
+              end
+
+              def open_proposals(**)
+                props = proposal_store.open_proposals
+                Legion::Logging.debug "[governance] open proposals: count=#{props.size}"
+                { proposals: props, count: props.size }
+              end
+
+              def timeout_proposals(**)
+                open  = proposal_store.open_proposals
+                timed = open.select { |p| Time.now.utc - p[:created_at] > Helpers::Layers::VOTE_TIMEOUT }
+                timed.each { |p| proposal_store.resolve_timed_out(p[:proposal_id]) }
+                timed_ids = timed.map { |p| p[:proposal_id] }
+                Legion::Logging.debug "[governance] vote timeout sweep: open=#{open.size} timed_out=#{timed.size}"
+                { checked: open.size, timed_out: timed.size, timed_out_ids: timed_ids }
+              end
+
+              def validate_action(layer:, action: nil, _context: {}, **) # rubocop:disable Lint/UnusedMethodArgument
+                return { error: :invalid_layer } unless Helpers::Layers.valid_layer?(layer)
+
+                result = case layer
+                         when :agent_validation
+                           { allowed: true, layer: layer, reason: :self_validated }
+                         when :anomaly_detection
+                           { allowed: true, layer: layer, reason: :no_anomaly }
+                         when :human_deliberation
+                           { allowed: false, layer: layer, reason: :requires_human_approval }
+                         when :transparency
+                           { allowed: true, layer: layer, reason: :logged, audit_required: true }
+                         end
+                Legion::Logging.debug "[governance] validate: layer=#{layer} allowed=#{result[:allowed]} reason=#{result[:reason]}"
+                result
+              end
+
+              private
+
+              def proposal_store
+                @proposal_store ||= Helpers::Proposal.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/governance/runners/shadow_ai.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Governance
+          module Runners
+            module ShadowAi
+              def scan_unregistered_extensions(**)
+                installed = Bundler.load.specs.select { |s| s.name.start_with?('lex-') }.map(&:name)
+                registered = registered_extension_names
+
+                unregistered = installed - registered
+                { installed: installed.size, registered: registered.size, unregistered: unregistered }
+              rescue StandardError => e
+                { installed: 0, registered: 0, unregistered: [], error: e.message }
+              end
+
+              def check_llm_bypass_indicators(**)
+                indicators = []
+                indicators << :direct_openai_key if ENV.key?('OPENAI_API_KEY') && !provider_enabled?(:openai)
+                indicators << :direct_anthropic_key if ENV.key?('ANTHROPIC_API_KEY') && !provider_enabled?(:anthropic)
+                { indicators: indicators, bypassed: !indicators.empty? }
+              end
+
+              def check_airb_compliance(**)
+                return { checked: 0, source: :unavailable } unless defined?(Legion::Data::Model::DigitalWorker)
+
+                workers = Legion::Data::Model::DigitalWorker.where(lifecycle_state: 'active').all
+                non_compliant = workers.select do |w|
+                  risk = w.respond_to?(:risk_tier) ? w.risk_tier : nil
+                  %w[high critical].include?(risk) && w.respond_to?(:airb_status) && w.airb_status != 'approved'
+                end
+
+                { checked: workers.size, compliant: workers.size - non_compliant.size,
+                  non_compliant: non_compliant.map(&:worker_id) }
+              rescue StandardError => e
+                { checked: 0, error: e.message }
+              end
+
+              def full_scan(**)
+                extensions = scan_unregistered_extensions
+                bypass = check_llm_bypass_indicators
+                compliance = check_airb_compliance
+
+                has_issues = extensions[:unregistered]&.any? || bypass[:bypassed] || compliance[:non_compliant]&.any?
+                emit_shadow_event(extensions, bypass, compliance) if has_issues
+
+                { extensions: extensions, bypass: bypass, compliance: compliance, issues_found: has_issues }
+              end
+
+              private
+
+              def registered_extension_names
+                return [] unless defined?(Legion::Data) && Legion::Data.respond_to?(:connection)
+
+                conn = Legion::Data.connection
+                return [] unless conn&.table_exists?(:extension_registry)
+
+                conn[:extension_registry].select_map(:gem_name)
+              rescue StandardError
+                []
+              end
+
+              def provider_enabled?(provider)
+                llm = Legion::Settings[:llm]
+                return false unless llm.is_a?(Hash)
+
+                providers = llm[:providers]
+                return false unless providers.is_a?(Hash)
+
+                providers.dig(provider, :enabled) == true
+              rescue StandardError
+                false
+              end
+
+              def emit_shadow_event(extensions, bypass, compliance)
+                return unless defined?(Legion::Events)
+
+                Legion::Events.emit('governance.shadow_ai_detected', {
+                                      unregistered:  extensions[:unregistered],
+                                      bypass:        bypass[:indicators],
+                                      non_compliant: compliance[:non_compliant]
+                                    })
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/governance/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Governance
+          VERSION = '0.2.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/governance.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/governance/version'
+require 'legion/extensions/agentic/social/governance/helpers/layers'
+require 'legion/extensions/agentic/social/governance/helpers/proposal'
+require 'legion/extensions/agentic/social/governance/runners/governance'
+require 'legion/extensions/agentic/social/governance/runners/shadow_ai'
+require 'legion/extensions/agentic/social/governance/actors/shadow_ai_scan'
+require 'legion/extensions/agentic/social/governance/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Governance
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/joint_attention/actors/decay.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module JointAttention
+          module Actor
+            class Decay < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Social::JointAttention::Runners::JointAttention
+              end
+
+              def runner_function
+                'update_joint_attention'
+              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
+  end
+end

data/lib/legion/extensions/agentic/social/joint_attention/client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/joint_attention/helpers/constants'
+require 'legion/extensions/agentic/social/joint_attention/helpers/attention_target'
+require 'legion/extensions/agentic/social/joint_attention/helpers/joint_focus_manager'
+require 'legion/extensions/agentic/social/joint_attention/runners/joint_attention'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module JointAttention
+          class Client
+            include Runners::JointAttention
+
+            def initialize(joint_focus_manager: nil, **)
+              @joint_focus_manager = joint_focus_manager || Helpers::JointFocusManager.new
+            end
+
+            private
+
+            attr_reader :joint_focus_manager
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/joint_attention/helpers/attention_target.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module JointAttention
+          module Helpers
+            class AttentionTarget
+              include Constants
+
+              attr_reader :id, :name, :domain, :priority, :creator_agent_id, :created_at, :attendees, :focus_strength
+
+              def initialize(name:, domain:, priority:, creator_agent_id:)
+                @id               = SecureRandom.uuid
+                @name             = name
+                @domain           = domain
+                @priority         = priority.clamp(0.0, 1.0)
+                @creator_agent_id = creator_agent_id
+                @created_at       = Time.now.utc
+                @attendees        = {}
+                @focus_strength   = DEFAULT_FOCUS
+              end
+
+              def add_attendee(agent_id:, gaze: nil)
+                return :at_capacity if @attendees.size >= MAX_ATTENDEES_PER_TARGET
+                return :already_attending if @attendees.key?(agent_id)
+
+                @attendees[agent_id] = {
+                  focus:            DEFAULT_FOCUS,
+                  gaze:             gaze,
+                  joined_at:        Time.now.utc,
+                  mutual_awareness: false
+                }
+                :joined
+              end
+
+              def remove_attendee(agent_id:)
+                return :not_found unless @attendees.key?(agent_id)
+
+                @attendees.delete(agent_id)
+                :removed
+              end
+
+              def update_gaze(agent_id:, gaze:)
+                return :not_found unless @attendees.key?(agent_id)
+
+                @attendees[agent_id][:gaze] = gaze
+                :updated
+              end
+
+              def boost_focus(agent_id:, amount:)
+                return :not_found unless @attendees.key?(agent_id)
+
+                current = @attendees[agent_id][:focus]
+                @attendees[agent_id][:focus] = [current + amount, 1.0].min
+                :boosted
+              end
+
+              def establish_mutual_awareness(agent_a:, agent_b:)
+                return :not_found unless @attendees.key?(agent_a) && @attendees.key?(agent_b)
+
+                bonus = SHARED_AWARENESS_BONUS
+                @attendees[agent_a][:mutual_awareness] = true
+                @attendees[agent_b][:mutual_awareness] = true
+                @attendees[agent_a][:focus] = [@attendees[agent_a][:focus] + bonus, 1.0].min
+                @attendees[agent_b][:focus] = [@attendees[agent_b][:focus] + bonus, 1.0].min
+                :established
+              end
+
+              def attendee_count
+                @attendees.size
+              end
+
+              def shared_awareness?
+                @attendees.count { |_, v| v[:mutual_awareness] } >= 2
+              end
+
+              def focus_label
+                FOCUS_LABELS.each { |range, lbl| return lbl if range.cover?(@focus_strength) }
+                :fading
+              end
+
+              def decay
+                @attendees.each_value do |info|
+                  info[:focus] = [info[:focus] - FOCUS_DECAY, FOCUS_FLOOR].max
+                end
+                @focus_strength = if @attendees.empty?
+                                    [@focus_strength - FOCUS_DECAY, FOCUS_FLOOR].max
+                                  else
+                                    @attendees.values.sum { |v| v[:focus] } / @attendees.size
+                                  end
+              end
+
+              def faded?
+                @focus_strength <= FOCUS_FLOOR && @attendees.empty?
+              end
+
+              def prune_faded_attendees
+                @attendees.reject! { |_, v| v[:focus] <= FOCUS_FLOOR }
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  name:             @name,
+                  domain:           @domain,
+                  priority:         @priority,
+                  creator_agent_id: @creator_agent_id,
+                  created_at:       @created_at,
+                  focus_strength:   @focus_strength.round(4),
+                  focus_label:      focus_label,
+                  attendee_count:   attendee_count,
+                  shared_awareness: shared_awareness?,
+                  attendees:        @attendees.transform_values { |v| v.merge(focus: v[:focus].round(4)) }
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/joint_attention/helpers/constants.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module JointAttention
+          module Helpers
+            module Constants
+              MAX_TARGETS              = 100
+              MAX_ATTENDEES_PER_TARGET = 20
+              MAX_HISTORY              = 200
+              FOCUS_DECAY              = 0.015
+              FOCUS_FLOOR              = 0.05
+              FOCUS_ALPHA              = 0.12
+              DEFAULT_FOCUS            = 0.5
+              SHARED_AWARENESS_BONUS   = 0.15
+              REFERRAL_BOOST           = 0.2
+              MAX_SIMULTANEOUS_TARGETS = 5
+
+              FOCUS_LABELS = {
+                (0.8..)     => :locked_on,
+                (0.6...0.8) => :focused,
+                (0.4...0.6) => :attending,
+                (0.2...0.4) => :peripheral,
+                (..0.2)     => :fading
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end