lex-agentic-social 0.1.0

data/spec/legion/extensions/agentic/social/joint_attention/client_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Social::JointAttention::Client do
+  subject(:client) { described_class.new }
+
+  it 'instantiates without arguments' do
+    expect(client).to be_a(described_class)
+  end
+
+  it 'accepts an injected joint_focus_manager' do
+    mgr = Legion::Extensions::Agentic::Social::JointAttention::Helpers::JointFocusManager.new
+    c = described_class.new(joint_focus_manager: mgr)
+    expect(c).to be_a(described_class)
+  end
+
+  it 'includes runner methods' do
+    expect(client).to respond_to(:create_attention_target)
+    expect(client).to respond_to(:join_attention)
+    expect(client).to respond_to(:leave_attention)
+    expect(client).to respond_to(:direct_attention)
+    expect(client).to respond_to(:establish_mutual_awareness)
+    expect(client).to respond_to(:update_gaze)
+    expect(client).to respond_to(:shared_focus)
+    expect(client).to respond_to(:attention_targets_for)
+    expect(client).to respond_to(:update_joint_attention)
+    expect(client).to respond_to(:joint_attention_stats)
+  end
+
+  it 'two clients maintain independent state' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.create_attention_target(name: 'only-in-c1', domain: :test, creator: 'agent-1')
+    expect(c1.joint_attention_stats[:stats][:target_count]).to eq(1)
+    expect(c2.joint_attention_stats[:stats][:target_count]).to eq(0)
+  end
+end

data/spec/legion/extensions/agentic/social/joint_attention/helpers/attention_target_spec.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Social::JointAttention::Helpers::AttentionTarget do
+  subject(:target) do
+    described_class.new(name: 'task-planning', domain: :collaboration, priority: 0.7, creator_agent_id: 'agent-1')
+  end
+
+  describe '#initialize' do
+    it 'assigns fields' do
+      expect(target.name).to eq('task-planning')
+      expect(target.domain).to eq(:collaboration)
+      expect(target.priority).to be_within(0.001).of(0.7)
+      expect(target.creator_agent_id).to eq('agent-1')
+    end
+
+    it 'assigns a uuid id' do
+      expect(target.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns created_at timestamp' do
+      expect(target.created_at).to be_a(Time)
+    end
+
+    it 'initializes with empty attendees' do
+      expect(target.attendees).to be_empty
+    end
+
+    it 'clamps priority to 0..1' do
+      t = described_class.new(name: 'x', domain: :d, priority: 2.0, creator_agent_id: 'a')
+      expect(t.priority).to eq(1.0)
+
+      t2 = described_class.new(name: 'x', domain: :d, priority: -0.5, creator_agent_id: 'a')
+      expect(t2.priority).to eq(0.0)
+    end
+
+    it 'sets default focus_strength' do
+      const = Legion::Extensions::Agentic::Social::JointAttention::Helpers::Constants::DEFAULT_FOCUS
+      expect(target.focus_strength).to eq(const)
+    end
+  end
+
+  describe '#add_attendee' do
+    it 'adds a new attendee and returns :joined' do
+      result = target.add_attendee(agent_id: 'agent-2')
+      expect(result).to eq(:joined)
+      expect(target.attendees).to have_key('agent-2')
+    end
+
+    it 'returns :already_attending when agent is already present' do
+      target.add_attendee(agent_id: 'agent-2')
+      result = target.add_attendee(agent_id: 'agent-2')
+      expect(result).to eq(:already_attending)
+    end
+
+    it 'stores gaze direction when provided' do
+      target.add_attendee(agent_id: 'agent-2', gaze: :risk_assessment)
+      expect(target.attendees['agent-2'][:gaze]).to eq(:risk_assessment)
+    end
+
+    it 'sets mutual_awareness to false by default' do
+      target.add_attendee(agent_id: 'agent-2')
+      expect(target.attendees['agent-2'][:mutual_awareness]).to be false
+    end
+
+    it 'returns :at_capacity when MAX_ATTENDEES_PER_TARGET is reached' do
+      max = Legion::Extensions::Agentic::Social::JointAttention::Helpers::Constants::MAX_ATTENDEES_PER_TARGET
+      max.times { |i| target.add_attendee(agent_id: "agent-#{i + 100}") }
+      result = target.add_attendee(agent_id: 'overflow-agent')
+      expect(result).to eq(:at_capacity)
+    end
+  end
+
+  describe '#remove_attendee' do
+    before { target.add_attendee(agent_id: 'agent-2') }
+
+    it 'removes attendee and returns :removed' do
+      result = target.remove_attendee(agent_id: 'agent-2')
+      expect(result).to eq(:removed)
+      expect(target.attendees).not_to have_key('agent-2')
+    end
+
+    it 'returns :not_found for unknown agent' do
+      expect(target.remove_attendee(agent_id: 'unknown')).to eq(:not_found)
+    end
+  end
+
+  describe '#update_gaze' do
+    before { target.add_attendee(agent_id: 'agent-2') }
+
+    it 'updates gaze and returns :updated' do
+      result = target.update_gaze(agent_id: 'agent-2', gaze: :timeline)
+      expect(result).to eq(:updated)
+      expect(target.attendees['agent-2'][:gaze]).to eq(:timeline)
+    end
+
+    it 'returns :not_found for unknown agent' do
+      expect(target.update_gaze(agent_id: 'ghost', gaze: :something)).to eq(:not_found)
+    end
+  end
+
+  describe '#boost_focus' do
+    before { target.add_attendee(agent_id: 'agent-2') }
+
+    it 'increases focus for the agent' do
+      before_val = target.attendees['agent-2'][:focus]
+      target.boost_focus(agent_id: 'agent-2', amount: 0.2)
+      expect(target.attendees['agent-2'][:focus]).to be > before_val
+    end
+
+    it 'caps focus at 1.0' do
+      target.boost_focus(agent_id: 'agent-2', amount: 5.0)
+      expect(target.attendees['agent-2'][:focus]).to eq(1.0)
+    end
+
+    it 'returns :not_found for unknown agent' do
+      expect(target.boost_focus(agent_id: 'ghost', amount: 0.1)).to eq(:not_found)
+    end
+  end
+
+  describe '#establish_mutual_awareness' do
+    before do
+      target.add_attendee(agent_id: 'agent-1')
+      target.add_attendee(agent_id: 'agent-2')
+    end
+
+    it 'sets mutual_awareness for both agents and returns :established' do
+      result = target.establish_mutual_awareness(agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(result).to eq(:established)
+      expect(target.attendees['agent-1'][:mutual_awareness]).to be true
+      expect(target.attendees['agent-2'][:mutual_awareness]).to be true
+    end
+
+    it 'boosts focus for both agents' do
+      before_a = target.attendees['agent-1'][:focus]
+      before_b = target.attendees['agent-2'][:focus]
+      target.establish_mutual_awareness(agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(target.attendees['agent-1'][:focus]).to be > before_a
+      expect(target.attendees['agent-2'][:focus]).to be > before_b
+    end
+
+    it 'returns :not_found when one agent is missing' do
+      result = target.establish_mutual_awareness(agent_a: 'agent-1', agent_b: 'ghost')
+      expect(result).to eq(:not_found)
+    end
+  end
+
+  describe '#attendee_count' do
+    it 'returns 0 initially' do
+      expect(target.attendee_count).to eq(0)
+    end
+
+    it 'increments when attendees join' do
+      target.add_attendee(agent_id: 'agent-2')
+      target.add_attendee(agent_id: 'agent-3')
+      expect(target.attendee_count).to eq(2)
+    end
+  end
+
+  describe '#shared_awareness?' do
+    it 'returns false with no mutual awareness' do
+      target.add_attendee(agent_id: 'agent-2')
+      expect(target.shared_awareness?).to be false
+    end
+
+    it 'returns true when two or more agents have mutual awareness' do
+      target.add_attendee(agent_id: 'agent-1')
+      target.add_attendee(agent_id: 'agent-2')
+      target.establish_mutual_awareness(agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(target.shared_awareness?).to be true
+    end
+  end
+
+  describe '#decay' do
+    before { target.add_attendee(agent_id: 'agent-2') }
+
+    it 'reduces attendee focus' do
+      before_val = target.attendees['agent-2'][:focus]
+      target.decay
+      expect(target.attendees['agent-2'][:focus]).to be < before_val
+    end
+
+    it 'does not drop focus below FOCUS_FLOOR' do
+      floor = Legion::Extensions::Agentic::Social::JointAttention::Helpers::Constants::FOCUS_FLOOR
+      200.times { target.decay }
+      expect(target.attendees['agent-2'][:focus]).to be >= floor
+    end
+
+    it 'updates overall focus_strength based on attendees' do
+      original = target.focus_strength
+      200.times { target.decay }
+      expect(target.focus_strength).to be <= original
+    end
+  end
+
+  describe '#faded?' do
+    it 'returns false when focus is above floor or attendees present' do
+      expect(target.faded?).to be false
+    end
+
+    it 'returns true when focus is at floor and no attendees' do
+      200.times { target.decay }
+      expect(target.faded?).to be true
+    end
+  end
+
+  describe '#prune_faded_attendees' do
+    it 'removes attendees whose focus is at or below FOCUS_FLOOR' do
+      target.add_attendee(agent_id: 'fading')
+      target.attendees['fading'][:focus] = Legion::Extensions::Agentic::Social::JointAttention::Helpers::Constants::FOCUS_FLOOR
+      target.prune_faded_attendees
+      expect(target.attendees).not_to have_key('fading')
+    end
+
+    it 'keeps attendees above floor' do
+      target.add_attendee(agent_id: 'active')
+      target.prune_faded_attendees
+      expect(target.attendees).to have_key('active')
+    end
+  end
+
+  describe '#focus_label' do
+    it 'returns :locked_on for high focus' do
+      target.instance_variable_set(:@focus_strength, 0.9)
+      expect(target.focus_label).to eq(:locked_on)
+    end
+
+    it 'returns :focused for 0.6..0.8 range' do
+      target.instance_variable_set(:@focus_strength, 0.7)
+      expect(target.focus_label).to eq(:focused)
+    end
+
+    it 'returns :attending for 0.4..0.6 range' do
+      target.instance_variable_set(:@focus_strength, 0.5)
+      expect(target.focus_label).to eq(:attending)
+    end
+
+    it 'returns :fading for very low focus' do
+      target.instance_variable_set(:@focus_strength, 0.1)
+      expect(target.focus_label).to eq(:fading)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all required fields' do
+      h = target.to_h
+      expect(h).to include(
+        :id, :name, :domain, :priority, :creator_agent_id,
+        :created_at, :focus_strength, :focus_label,
+        :attendee_count, :shared_awareness, :attendees
+      )
+    end
+
+    it 'rounds focus_strength to 4 decimal places' do
+      target.instance_variable_set(:@focus_strength, 0.123456789)
+      expect(target.to_h[:focus_strength]).to eq(0.1235)
+    end
+  end
+end

data/spec/legion/extensions/agentic/social/joint_attention/helpers/joint_focus_manager_spec.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Social::JointAttention::Helpers::JointFocusManager do
+  subject(:manager) { described_class.new }
+
+  let!(:target) do
+    manager.create_target(name: 'task-alpha', domain: :planning, priority: 0.8, creator: 'agent-1')
+  end
+
+  describe '#create_target' do
+    it 'creates a target and returns an AttentionTarget' do
+      expect(target).to be_a(Legion::Extensions::Agentic::Social::JointAttention::Helpers::AttentionTarget)
+      expect(target.name).to eq('task-alpha')
+    end
+
+    it 'adds the target to @targets' do
+      expect(manager.targets).to have_key(target.id)
+    end
+
+    it 'auto-joins the creator' do
+      expect(target.attendees).to have_key('agent-1')
+    end
+
+    it 'records history' do
+      expect(manager.history).not_to be_empty
+      expect(manager.history.last[:event]).to eq(:agent_joined)
+    end
+
+    it 'increments target_count' do
+      expect(manager.target_count).to eq(1)
+    end
+  end
+
+  describe '#join_target' do
+    it 'adds a second agent to the target' do
+      result = manager.join_target(target_id: target.id, agent_id: 'agent-2')
+      expect(result).to eq(:joined)
+      expect(target.attendees).to have_key('agent-2')
+    end
+
+    it 'returns :target_not_found for unknown target' do
+      result = manager.join_target(target_id: 'bogus', agent_id: 'agent-2')
+      expect(result).to eq(:target_not_found)
+    end
+
+    it 'returns :already_attending when agent already there' do
+      manager.join_target(target_id: target.id, agent_id: 'agent-2')
+      result = manager.join_target(target_id: target.id, agent_id: 'agent-2')
+      expect(result).to eq(:already_attending)
+    end
+
+    it 'enforces MAX_SIMULTANEOUS_TARGETS per agent' do
+      max = Legion::Extensions::Agentic::Social::JointAttention::Helpers::Constants::MAX_SIMULTANEOUS_TARGETS
+      max.times do |i|
+        t = manager.create_target(name: "agent-x-target-#{i}", domain: :d, priority: 0.5, creator: 'other')
+        manager.join_target(target_id: t.id, agent_id: 'agent-x')
+      end
+      extra = manager.create_target(name: 'overflow', domain: :d, priority: 0.5, creator: 'other2')
+      result = manager.join_target(target_id: extra.id, agent_id: 'agent-x')
+      expect(result).to eq(:capacity_exceeded)
+    end
+
+    it 'records join history' do
+      manager.join_target(target_id: target.id, agent_id: 'agent-3')
+      events = manager.history.map { |h| h[:event] }
+      expect(events).to include(:agent_joined)
+    end
+  end
+
+  describe '#leave_target' do
+    before { manager.join_target(target_id: target.id, agent_id: 'agent-2') }
+
+    it 'removes the agent and returns :removed' do
+      result = manager.leave_target(target_id: target.id, agent_id: 'agent-2')
+      expect(result).to eq(:removed)
+      expect(target.attendees).not_to have_key('agent-2')
+    end
+
+    it 'returns :target_not_found for unknown target' do
+      result = manager.leave_target(target_id: 'bogus', agent_id: 'agent-2')
+      expect(result).to eq(:target_not_found)
+    end
+
+    it 'returns :not_found when agent not attending' do
+      result = manager.leave_target(target_id: target.id, agent_id: 'never-joined')
+      expect(result).to eq(:not_found)
+    end
+
+    it 'records leave history' do
+      manager.leave_target(target_id: target.id, agent_id: 'agent-2')
+      events = manager.history.map { |h| h[:event] }
+      expect(events).to include(:agent_left)
+    end
+  end
+
+  describe '#direct_attention' do
+    before { manager.join_target(target_id: target.id, agent_id: 'agent-1') }
+
+    it 'joins recipient to target and returns :directed' do
+      result = manager.direct_attention(from_agent: 'agent-1', to_agent: 'agent-2', target_id: target.id)
+      expect(result).to eq(:directed)
+      expect(target.attendees).to have_key('agent-2')
+    end
+
+    it 'returns :target_not_found for unknown target' do
+      result = manager.direct_attention(from_agent: 'agent-1', to_agent: 'agent-2', target_id: 'bogus')
+      expect(result).to eq(:target_not_found)
+    end
+
+    it 'returns :referrer_not_attending when from_agent is not on target' do
+      result = manager.direct_attention(from_agent: 'nobody', to_agent: 'agent-2', target_id: target.id)
+      expect(result).to eq(:referrer_not_attending)
+    end
+
+    it 'boosts focus of recipient' do
+      manager.direct_attention(from_agent: 'agent-1', to_agent: 'agent-2', target_id: target.id)
+      const = Legion::Extensions::Agentic::Social::JointAttention::Helpers::Constants
+      expected_min = const::DEFAULT_FOCUS + const::REFERRAL_BOOST
+      expect(target.attendees['agent-2'][:focus]).to be >= expected_min
+    end
+
+    it 'records direction history' do
+      manager.direct_attention(from_agent: 'agent-1', to_agent: 'agent-2', target_id: target.id)
+      events = manager.history.map { |h| h[:event] }
+      expect(events).to include(:attention_directed)
+    end
+  end
+
+  describe '#establish_shared' do
+    before do
+      manager.join_target(target_id: target.id, agent_id: 'agent-1')
+      manager.join_target(target_id: target.id, agent_id: 'agent-2')
+    end
+
+    it 'establishes mutual awareness and returns :established' do
+      result = manager.establish_shared(target_id: target.id, agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(result).to eq(:established)
+      expect(target.attendees['agent-1'][:mutual_awareness]).to be true
+      expect(target.attendees['agent-2'][:mutual_awareness]).to be true
+    end
+
+    it 'returns :target_not_found for unknown target' do
+      result = manager.establish_shared(target_id: 'bogus', agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(result).to eq(:target_not_found)
+    end
+
+    it 'records shared_awareness history event' do
+      manager.establish_shared(target_id: target.id, agent_a: 'agent-1', agent_b: 'agent-2')
+      events = manager.history.map { |h| h[:event] }
+      expect(events).to include(:shared_awareness)
+    end
+  end
+
+  describe '#update_gaze' do
+    before { manager.join_target(target_id: target.id, agent_id: 'agent-1') }
+
+    it 'updates gaze direction' do
+      result = manager.update_gaze(target_id: target.id, agent_id: 'agent-1', gaze: :timeline)
+      expect(result).to eq(:updated)
+    end
+
+    it 'returns :target_not_found for unknown target' do
+      result = manager.update_gaze(target_id: 'bogus', agent_id: 'agent-1', gaze: :x)
+      expect(result).to eq(:target_not_found)
+    end
+  end
+
+  describe '#targets_for_agent' do
+    it 'returns targets the agent is attending' do
+      targets = manager.targets_for_agent(agent_id: 'agent-1')
+      expect(targets).to include(target)
+    end
+
+    it 'returns empty array for unknown agent' do
+      expect(manager.targets_for_agent(agent_id: 'nobody')).to eq([])
+    end
+  end
+
+  describe '#attendees_for_target' do
+    before { manager.join_target(target_id: target.id, agent_id: 'agent-2') }
+
+    it 'returns attendee ids for target' do
+      ids = manager.attendees_for_target(target_id: target.id)
+      expect(ids).to include('agent-1', 'agent-2')
+    end
+
+    it 'returns empty array for unknown target' do
+      expect(manager.attendees_for_target(target_id: 'bogus')).to eq([])
+    end
+  end
+
+  describe '#shared_targets' do
+    it 'returns targets attended by both agents' do
+      manager.join_target(target_id: target.id, agent_id: 'agent-2')
+      shared = manager.shared_targets(agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(shared).to include(target)
+    end
+
+    it 'returns empty array when no shared targets' do
+      shared = manager.shared_targets(agent_a: 'agent-1', agent_b: 'loner')
+      expect(shared).to be_empty
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays focus on all targets' do
+      focus_before = target.focus_strength
+      manager.decay_all
+      expect(target.focus_strength).to be <= focus_before
+    end
+
+    it 'prunes faded targets' do
+      t = manager.create_target(name: 'doomed', domain: :temp, priority: 0.1, creator: 'agent-x')
+      # Drain all attendees so target can become faded
+      manager.leave_target(target_id: t.id, agent_id: 'agent-x')
+      200.times { manager.decay_all }
+      expect(manager.targets).not_to have_key(t.id)
+    end
+  end
+
+  describe '#target_count' do
+    it 'returns number of active targets' do
+      manager.create_target(name: 'b', domain: :d, priority: 0.5, creator: 'a')
+      expect(manager.target_count).to eq(2)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a summary hash' do
+      h = manager.to_h
+      expect(h).to include(:target_count, :agent_count, :history_size, :targets)
+    end
+
+    it 'reflects correct target count' do
+      expect(manager.to_h[:target_count]).to eq(1)
+    end
+  end
+end