lex-agentic-social 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a01aa481409269257996188227484fe5ad8f1bd8e4c16abd0a8922ce3b312b8
-  data.tar.gz: 4ecb04ebefef8d08763f840c3233da964592c58216597d42963da27f44f1d8a7
+  metadata.gz: 1e4e4cf74f2655992c34c4945a8da0de92c597fc5371ff6fa595e583a4cdd88a
+  data.tar.gz: b0696e9bc1f7b990fb8e3a153fd22755edf34e18a6fdce7ea7efe23eccaa5afb
 SHA512:
-  metadata.gz: d2372a7bfab7f4f52b9389ef120e7f851e81755b71f07272ba63c572704424eef92045201815e93b55866cced472cfa3a06d00e2343c33b9523e5b0adc0a7732
-  data.tar.gz: 50ef5117fe9183f54c6b02ef84df4f130c010701d266156820bed6e4654755009c7772202ab84a39588691879096fd68e9301ee63ce5b28bf471bb26e781c15d
+  metadata.gz: 362432beb980f6e62f4097db1c37f444929ce2edd84439daee258de6e15dae346b5c33b09e3bfab19b2ca5d38ecd75b8f65269099247586750c329e05f5e7728
+  data.tar.gz: 1309465c2e0655fe62b68b3bfb58cf4f07eb9bbd808215927eb64c240dd4a16575117eb1e3cf6c757d7cd40e586bf3416ce4ddc3ba7feb040d8b2589f6f34c9a

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.1.6] - 2026-03-31
+
+### Added
+- `update_social` accepts `human_observations:` kwarg; processes each observation into reputation signals (partner: 0.8 confidence, others: 0.5) and records communication reciprocity
+- `SocialGraph#reputation_changes` array tracks dimension-level changes per update cycle; cleared at start of each `update_social` call
+- `update_social` return hash includes `:reputation_updates` key with agent-level summary
+- `update_theory_of_mind` accepts `human_observations:` kwarg; builds communication and channel-preference beliefs, infers engagement intent from direct-address observations, validates pending predictions
+- `MentalStateTracker#pending_prediction(agent_id:)` returns most recent unvalidated prediction log entry
+- Dirty tracking (`dirty?`, `mark_clean!`) on `SocialGraph` and `MentalStateTracker`
+- Apollo Local persistence (`to_apollo_entries`, `from_apollo`, `mark_clean!`) on `SocialGraph` and `MentalStateTracker`; partner agents tagged with `'partner'` when `Legion::Gaia::BondRegistry` is present
+
 ## [0.1.5] - 2026-03-30
 
 ### Changed

data/lib/legion/extensions/agentic/social/social/helpers/social_graph.rb

@@ -7,12 +7,50 @@ module Legion
         module Social
           module Helpers
             class SocialGraph
-              attr_reader :groups, :reputation_scores, :reciprocity_ledger
+              attr_reader :groups, :reputation_scores, :reciprocity_ledger, :reputation_changes
 
               def initialize
                 @groups = {}
                 @reputation_scores = {}
                 @reciprocity_ledger = []
+                @reputation_changes = []
+                @dirty = false
+              end
+
+              def dirty?
+                @dirty
+              end
+
+              def mark_clean!
+                @dirty = false
+                self
+              end
+
+              def clear_reputation_changes!
+                @reputation_changes = []
+              end
+
+              def to_apollo_entries
+                @reputation_scores.map do |agent_id, scores|
+                  tags = build_apollo_tags(agent_id)
+                  content = Legion::JSON.dump({
+                                                agent_id:   agent_id.to_s,
+                                                scores:     scores,
+                                                updated_at: Time.now.utc.iso8601
+                                              })
+                  { content: content, tags: tags }
+                end
+              end
+
+              def from_apollo(store:)
+                result = store.query(text: 'social_graph reputation', tags: %w[social_graph reputation])
+                return false unless result[:success] && result[:results]&.any?
+
+                result[:results].each { |entry| restore_from_entry(entry) }
+                true
+              rescue StandardError => e
+                Legion::Logging.warn("[social_graph] from_apollo error: #{e.message}")
+                false
               end
 
               def join_group(group_id:, role: :contributor, members: [])
@@ -25,6 +63,7 @@ module Legion
                   violations: []
                 }
                 trim_groups
+                @dirty = true
                 @groups[group_id]
               end
 
@@ -44,7 +83,11 @@ module Legion
 
                 @reputation_scores[agent_id] ||= Constants::REPUTATION_DIMENSIONS.keys.to_h { |d| [d, 0.5] }
                 current = @reputation_scores[agent_id][dimension]
-                @reputation_scores[agent_id][dimension] = ema(current, signal.clamp(0.0, 1.0), Constants::REPUTATION_ALPHA)
+                new_score = ema(current, signal.clamp(0.0, 1.0), Constants::REPUTATION_ALPHA)
+                @reputation_scores[agent_id][dimension] = new_score
+                @reputation_changes << { agent_id: agent_id, dimension: dimension, score: new_score }
+                @dirty = true
+                new_score
               end
 
               def reputation_for(agent_id)
@@ -80,6 +123,7 @@ module Legion
                   at:        Time.now.utc
                 }
                 @reciprocity_ledger.shift while @reciprocity_ledger.size > Constants::RECIPROCITY_WINDOW
+                @dirty = true
               end
 
               def reciprocity_balance(agent_id)
@@ -163,6 +207,35 @@ module Legion
                 oldest = @groups.keys.sort_by { |k| @groups[k][:joined_at] }
                 oldest.first([@groups.size - Constants::MAX_GROUPS, 0].max).each { |k| @groups.delete(k) }
               end
+
+              def build_apollo_tags(agent_id)
+                tags = ['social_graph', 'reputation', agent_id.to_s]
+                tags << 'partner' if defined?(Legion::Gaia::BondRegistry) && partner_agent?(agent_id)
+                tags
+              end
+
+              def partner_agent?(agent_id)
+                Legion::Gaia::BondRegistry.partner?(agent_id.to_s)
+              rescue StandardError => e
+                Legion::Logging.debug("[social_graph] BondRegistry check failed: #{e.message}")
+                false
+              end
+
+              def restore_from_entry(entry)
+                data = Legion::JSON.parse(entry[:content])
+                agent_id = data['agent_id'] || data[:agent_id]
+                return unless agent_id
+
+                scores = data['scores'] || data[:scores] || {}
+                stored = scores.transform_keys(&:to_sym)
+                @reputation_scores[agent_id] ||= Constants::REPUTATION_DIMENSIONS.keys.to_h { |d| [d, 0.5] }
+                stored.each do |dim, val|
+                  @reputation_scores[agent_id][dim] = val.to_f if Constants::REPUTATION_DIMENSIONS.key?(dim)
+                end
+              rescue StandardError => e
+                Legion::Logging.debug("[social_graph] restore entry failed: #{e.message}")
+                nil
+              end
             end
           end
         end

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

@@ -10,17 +10,20 @@ module Legion
               include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
                                                           Legion::Extensions::Helpers.const_defined?(:Lex, false)
 
-              def update_social(tick_results: {}, **)
+              def update_social(tick_results: {}, human_observations: [], **)
+                social_graph.clear_reputation_changes!
                 extract_social_signals(tick_results)
+                process_human_observations(human_observations)
 
                 log.debug "[social] groups=#{social_graph.group_count} " \
                           "agents=#{social_graph.agents_tracked} standing=#{social_graph.social_standing}"
 
                 {
-                  groups:         social_graph.group_count,
-                  agents_tracked: social_graph.agents_tracked,
-                  standing:       social_graph.social_standing,
-                  ledger_size:    social_graph.reciprocity_ledger.size
+                  groups:             social_graph.group_count,
+                  agents_tracked:     social_graph.agents_tracked,
+                  standing:           social_graph.social_standing,
+                  ledger_size:        social_graph.reciprocity_ledger.size,
+                  reputation_updates: build_reputation_updates
                 }
               end
 
@@ -111,6 +114,38 @@ module Legion
                 @social_graph ||= Helpers::SocialGraph.new
               end
 
+              def process_human_observations(human_observations)
+                human_observations.each do |obs|
+                  agent_id   = obs[:identity].to_s
+                  confidence = obs[:bond_role] == :partner ? 0.8 : 0.5
+
+                  social_graph.update_reputation(
+                    agent_id:  agent_id,
+                    dimension: :reliability,
+                    signal:    confidence
+                  )
+                  social_graph.record_reciprocity(
+                    agent_id:  agent_id,
+                    action:    obs[:content_type] || :text,
+                    direction: :received
+                  )
+                end
+              end
+
+              def build_reputation_updates
+                social_graph.reputation_changes
+                            .group_by { |c| c[:agent_id] }
+                            .map do |agent_id, changes|
+                  rep = social_graph.reputation_for(agent_id)
+                  {
+                    agent_id:  agent_id,
+                    changes:   changes,
+                    composite: rep&.dig(:composite),
+                    standing:  rep&.dig(:standing)
+                  }
+                end
+              end
+
               def extract_social_signals(tick_results)
                 extract_trust_signals(tick_results)
                 extract_mesh_signals(tick_results)

data/lib/legion/extensions/agentic/social/theory_of_mind/helpers/mental_state_tracker.rb

@@ -12,6 +12,40 @@ module Legion
               def initialize
                 @agent_models = {}
                 @prediction_log = []
+                @dirty = false
+              end
+
+              def dirty?
+                @dirty
+              end
+
+              def mark_clean!
+                @dirty = false
+                self
+              end
+
+              def to_apollo_entries
+                @agent_models.map do |agent_id, model|
+                  tags = build_apollo_tags(agent_id)
+                  content = Legion::JSON.dump({
+                                                agent_id:   agent_id.to_s,
+                                                beliefs:    serialize_beliefs(model.beliefs),
+                                                desires:    model.desires,
+                                                intentions: model.intentions
+                                              })
+                  { content: content, tags: tags }
+                end
+              end
+
+              def from_apollo(store:)
+                result = store.query(text: 'theory_of_mind agent_model', tags: %w[theory_of_mind agent_model])
+                return false unless result[:success] && result[:results]&.any?
+
+                result[:results].each { |entry| restore_from_entry(entry) }
+                true
+              rescue StandardError => e
+                Legion::Logging.warn("[mental_state_tracker] from_apollo error: #{e.message}")
+                false
               end
 
               def model_for(agent_id)
@@ -23,16 +57,19 @@ module Legion
               def update_belief(agent_id:, domain:, content:, confidence:, source: :inference)
                 model = model_for(agent_id)
                 model.update_belief(domain: domain, content: content, confidence: confidence, source: source)
+                @dirty = true
               end
 
               def update_desire(agent_id:, goal:, priority: :medium)
                 model = model_for(agent_id)
                 model.update_desire(goal: goal, priority: priority)
+                @dirty = true
               end
 
               def infer_intention(agent_id:, action:, confidence: :possible)
                 model = model_for(agent_id)
                 model.update_intention(action: action, confidence: confidence)
+                @dirty = true
               end
 
               def predict_behavior(agent_id:, context: {})
@@ -91,6 +128,10 @@ module Legion
                 }
               end
 
+              def pending_prediction(agent_id:)
+                @prediction_log.reverse.find { |p| p[:agent_id] == agent_id }
+              end
+
               def decay_all
                 @agent_models.each_value(&:decay_beliefs)
                 @agent_models.reject! { |_, m| m.beliefs.empty? && m.desires.empty? && m.intentions.empty? }
@@ -160,6 +201,68 @@ module Legion
               def trim_prediction_log
                 @prediction_log.shift while @prediction_log.size > 200
               end
+
+              def build_apollo_tags(agent_id)
+                tags = ['theory_of_mind', 'agent_model', agent_id.to_s]
+                tags << 'partner' if defined?(Legion::Gaia::BondRegistry) && partner_agent?(agent_id)
+                tags
+              end
+
+              def partner_agent?(agent_id)
+                Legion::Gaia::BondRegistry.partner?(agent_id.to_s)
+              rescue StandardError => e
+                Legion::Logging.debug("[mental_state_tracker] BondRegistry check failed: #{e.message}")
+                false
+              end
+
+              def serialize_beliefs(beliefs)
+                beliefs.transform_keys(&:to_s).transform_values do |b|
+                  b.merge(updated_at: b[:updated_at]&.iso8601)
+                end
+              end
+
+              def restore_from_entry(entry)
+                data = Legion::JSON.parse(entry[:content])
+                agent_id = data['agent_id'] || data[:agent_id]
+                return unless agent_id
+
+                model = model_for(agent_id)
+                restore_beliefs(model, data['beliefs'] || {})
+                restore_desires(model, data['desires'] || [])
+                restore_intentions(model, data['intentions'] || [])
+              rescue StandardError => e
+                Legion::Logging.debug("[mental_state_tracker] restore entry failed: #{e.message}")
+                nil
+              end
+
+              def restore_beliefs(model, beliefs_data)
+                beliefs_data.each do |domain, belief|
+                  model.update_belief(
+                    domain:     domain.to_sym,
+                    content:    belief['content'],
+                    confidence: belief['confidence'].to_f,
+                    source:     (belief['source'] || :restored).to_sym
+                  )
+                end
+              end
+
+              def restore_desires(model, desires_data)
+                desires_data.each do |desire|
+                  model.update_desire(
+                    goal:     desire['goal'],
+                    priority: (desire['priority'] || :medium).to_sym
+                  )
+                end
+              end
+
+              def restore_intentions(model, intentions_data)
+                intentions_data.each do |intention|
+                  model.update_intention(
+                    action:     intention['action'].to_sym,
+                    confidence: (intention['confidence'] || :possible).to_sym
+                  )
+                end
+              end
             end
           end
         end

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

@@ -10,9 +10,10 @@ module Legion
               include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
                                                           Legion::Extensions::Helpers.const_defined?(:Lex, false)
 
-              def update_theory_of_mind(tick_results: {}, **)
+              def update_theory_of_mind(tick_results: {}, human_observations: [], **)
                 extract_social_observations(tick_results)
                 extract_mesh_observations(tick_results)
+                process_tom_human_observations(human_observations)
                 tracker.decay_all
 
                 log.debug "[tom] agents=#{tracker.agents_tracked} " \
@@ -121,6 +122,51 @@ module Legion
                 tracker.infer_intention(agent_id: agent_id, action: obs[:action], confidence: obs[:action_confidence] || :possible)
               end
 
+              def process_tom_human_observations(human_observations)
+                human_observations.each do |obs|
+                  agent_id = obs[:identity].to_s
+                  validate_pending_prediction(agent_id)
+                  build_communication_belief(agent_id, obs)
+                  infer_engagement_intention(agent_id, obs) if obs[:direct_address]
+                  infer_channel_preference(agent_id, obs)
+                end
+              end
+
+              def validate_pending_prediction(agent_id)
+                pending = tracker.pending_prediction(agent_id: agent_id)
+                return unless pending
+
+                tracker.record_prediction_outcome(agent_id: agent_id, outcome: :correct)
+              end
+
+              def build_communication_belief(agent_id, obs)
+                channel = obs[:channel] || :unknown
+                tracker.update_belief(
+                  agent_id:   agent_id,
+                  domain:     :communication,
+                  content:    channel,
+                  confidence: 0.7,
+                  source:     :direct_observation
+                )
+              end
+
+              def infer_engagement_intention(agent_id, obs)
+                confidence = obs[:bond_role] == :partner ? :certain : :likely
+                tracker.infer_intention(agent_id: agent_id, action: :engage, confidence: confidence)
+              end
+
+              def infer_channel_preference(agent_id, obs)
+                return unless obs[:channel]
+
+                tracker.update_belief(
+                  agent_id:   agent_id,
+                  domain:     :channel_preference,
+                  content:    obs[:channel],
+                  confidence: 0.6,
+                  source:     :direct_observation
+                )
+              end
+
               def extract_social_observations(tick_results)
                 social = tick_results.dig(:social, :reputation_updates)
                 return unless social.is_a?(Array)

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Agentic
       module Social
-        VERSION = '0.1.5'
+        VERSION = '0.1.6'
       end
     end
   end

data/spec/legion/extensions/agentic/social/social/helpers/social_graph_spec.rb

@@ -319,4 +319,114 @@ RSpec.describe Legion::Extensions::Agentic::Social::Social::Helpers::SocialGraph
       expect(result).to have_key(:ledger_size)
     end
   end
+
+  describe '#dirty?' do
+    it 'starts clean' do
+      expect(graph.dirty?).to be false
+    end
+
+    it 'becomes dirty after reputation update' do
+      graph.update_reputation(agent_id: :a1, dimension: :reliability, signal: 0.8)
+      expect(graph.dirty?).to be true
+    end
+
+    it 'becomes dirty after joining a group' do
+      graph.join_group(group_id: :alpha)
+      expect(graph.dirty?).to be true
+    end
+
+    it 'becomes dirty after recording reciprocity' do
+      graph.record_reciprocity(agent_id: :a1, action: :helped, direction: :given)
+      expect(graph.dirty?).to be true
+    end
+
+    it 'becomes clean after mark_clean!' do
+      graph.update_reputation(agent_id: :a1, dimension: :reliability, signal: 0.8)
+      graph.mark_clean!
+      expect(graph.dirty?).to be false
+    end
+  end
+
+  describe '#to_apollo_entries' do
+    it 'returns empty array when no reputation scores' do
+      expect(graph.to_apollo_entries).to eq([])
+    end
+
+    it 'returns one entry per tracked agent' do
+      graph.update_reputation(agent_id: :a1, dimension: :reliability, signal: 0.8)
+      graph.update_reputation(agent_id: :a2, dimension: :competence, signal: 0.7)
+      expect(graph.to_apollo_entries.size).to eq(2)
+    end
+
+    it 'entry content is a JSON string' do
+      graph.update_reputation(agent_id: :a1, dimension: :reliability, signal: 0.8)
+      entry = graph.to_apollo_entries.first
+      parsed = JSON.parse(entry[:content])
+      expect(parsed).to have_key('agent_id')
+    end
+
+    it 'entry tags include social_graph, reputation, and agent_id' do
+      graph.update_reputation(agent_id: :a1, dimension: :reliability, signal: 0.8)
+      entry = graph.to_apollo_entries.first
+      expect(entry[:tags]).to include('social_graph', 'reputation')
+      expect(entry[:tags].any? { |t| t.to_s == 'a1' }).to be true
+    end
+  end
+
+  describe '#from_apollo' do
+    let(:mock_store) do
+      double('ApolloLocal').tap do |store|
+        allow(store).to receive(:query).and_return({ success: false, results: [] })
+      end
+    end
+
+    it 'returns false when store query fails or returns no results' do
+      result = graph.from_apollo(store: mock_store)
+      expect(result).to be false
+    end
+
+    it 'populates reputation_scores from stored JSON' do
+      scores = { reliability: 0.8, competence: 0.7, benevolence: 0.5, integrity: 0.5, influence: 0.5 }
+      content = JSON.dump({ agent_id: 'a1', scores: scores, updated_at: Time.now.utc.iso8601 })
+      allow(mock_store).to receive(:query).and_return(
+        { success: true, results: [{ content: content, tags: '["social_graph","reputation","a1"]' }] }
+      )
+      graph.from_apollo(store: mock_store)
+      expect(graph.reputation_scores['a1']).not_to be_nil
+    end
+  end
+
+  describe '#mark_clean!' do
+    it 'returns self' do
+      expect(graph.mark_clean!).to eq(graph)
+    end
+
+    it 'resets dirty flag' do
+      graph.update_reputation(agent_id: :a1, dimension: :reliability, signal: 0.5)
+      graph.mark_clean!
+      expect(graph.dirty?).to be false
+    end
+  end
+
+  describe '#reputation_changes' do
+    it 'starts empty' do
+      expect(graph.reputation_changes).to eq([])
+    end
+
+    it 'records a change when reputation is updated' do
+      graph.update_reputation(agent_id: :a1, dimension: :reliability, signal: 0.8)
+      expect(graph.reputation_changes).not_to be_empty
+    end
+
+    it 'records agent_id in the change entry' do
+      graph.update_reputation(agent_id: :a1, dimension: :reliability, signal: 0.8)
+      expect(graph.reputation_changes.first[:agent_id]).to eq(:a1)
+    end
+
+    it 'clears reputation_changes on clear_reputation_changes!' do
+      graph.update_reputation(agent_id: :a1, dimension: :reliability, signal: 0.8)
+      graph.clear_reputation_changes!
+      expect(graph.reputation_changes).to be_empty
+    end
+  end
 end

data/spec/legion/extensions/agentic/social/social/runners/social_spec.rb

@@ -216,5 +216,77 @@ RSpec.describe Legion::Extensions::Agentic::Social::Social::Runners::Social do
       host.update_social(tick_results: tick)
       expect(graph.group_cohesion(:alpha)).to eq(initial_cohesion)
     end
+
+    it 'returns :reputation_updates key' do
+      result = host.update_social(tick_results: {})
+      expect(result).to have_key(:reputation_updates)
+      expect(result[:reputation_updates]).to be_an(Array)
+    end
+
+    it 'processes human_observations and creates agent reputation entries' do
+      obs = [
+        {
+          identity:       'esity',
+          bond_role:      :partner,
+          channel:        :cli,
+          content_type:   :text,
+          content_length: 50,
+          direct_address: false,
+          timestamp:      Time.now.utc
+        }
+      ]
+      host.update_social(tick_results: {}, human_observations: obs)
+      expect(graph.agents_tracked).to be >= 1
+      expect(graph.reputation_scores['esity']).not_to be_nil
+    end
+
+    it 'gives partner observations higher initial confidence than strangers' do
+      partner_obs = [
+        { identity: 'partner_agent', bond_role: :partner, channel: :cli,
+          content_type: :text, content_length: 10, direct_address: false, timestamp: Time.now.utc }
+      ]
+      stranger_obs = [
+        { identity: 'stranger_agent', bond_role: :unknown, channel: :cli,
+          content_type: :text, content_length: 10, direct_address: false, timestamp: Time.now.utc }
+      ]
+
+      graph2 = Legion::Extensions::Agentic::Social::Social::Helpers::SocialGraph.new
+      host2 = Object.new.tap do |obj|
+        obj.extend(described_class)
+        obj.instance_variable_set(:@social_graph, graph2)
+      end
+
+      host.update_social(tick_results: {}, human_observations: partner_obs)
+      host2.update_social(tick_results: {}, human_observations: stranger_obs)
+
+      partner_score = graph.reputation_scores['partner_agent']
+      stranger_score = graph2.reputation_scores['stranger_agent']
+
+      partner_composite = partner_score.values.sum / partner_score.size.to_f
+      stranger_composite = stranger_score.values.sum / stranger_score.size.to_f
+
+      expect(partner_composite).to be > stranger_composite
+    end
+
+    it 'records communication reciprocity for each observation' do
+      obs = [
+        { identity: 'alice', bond_role: :known, channel: :cli,
+          content_type: :text, content_length: 20, direct_address: true, timestamp: Time.now.utc }
+      ]
+      host.update_social(tick_results: {}, human_observations: obs)
+      balance = graph.reciprocity_balance('alice')
+      expect(balance[:received]).to eq(1)
+    end
+
+    it 'reputation_updates in result includes entries for processed observations' do
+      obs = [
+        { identity: 'bob', bond_role: :partner, channel: :cli,
+          content_type: :text, content_length: 30, direct_address: false, timestamp: Time.now.utc }
+      ]
+      result = host.update_social(tick_results: {}, human_observations: obs)
+      expect(result[:reputation_updates]).not_to be_empty
+      entry = result[:reputation_updates].first
+      expect(entry[:agent_id]).to eq('bob')
+    end
   end
 end

data/spec/legion/extensions/agentic/social/theory_of_mind/helpers/mental_state_tracker_spec.rb

@@ -225,4 +225,120 @@ RSpec.describe Legion::Extensions::Agentic::Social::TheoryOfMind::Helpers::Menta
       expect(result).to have_key(:prediction_log_size)
     end
   end
+
+  describe '#dirty?' do
+    it 'starts clean' do
+      expect(tracker.dirty?).to be false
+    end
+
+    it 'becomes dirty after update_belief' do
+      tracker.update_belief(agent_id: :a1, domain: :test, content: 'v', confidence: 0.8)
+      expect(tracker.dirty?).to be true
+    end
+
+    it 'becomes dirty after update_desire' do
+      tracker.update_desire(agent_id: :a1, goal: 'deploy')
+      expect(tracker.dirty?).to be true
+    end
+
+    it 'becomes dirty after infer_intention' do
+      tracker.infer_intention(agent_id: :a1, action: :send)
+      expect(tracker.dirty?).to be true
+    end
+
+    it 'becomes clean after mark_clean!' do
+      tracker.update_belief(agent_id: :a1, domain: :test, content: 'v', confidence: 0.8)
+      tracker.mark_clean!
+      expect(tracker.dirty?).to be false
+    end
+  end
+
+  describe '#to_apollo_entries' do
+    it 'returns empty array when no agent models' do
+      expect(tracker.to_apollo_entries).to eq([])
+    end
+
+    it 'returns one entry per tracked agent' do
+      tracker.update_belief(agent_id: :a1, domain: :x, content: 'v', confidence: 0.9)
+      tracker.update_belief(agent_id: :a2, domain: :y, content: 'w', confidence: 0.8)
+      expect(tracker.to_apollo_entries.size).to eq(2)
+    end
+
+    it 'entry content is a JSON string with agent_id' do
+      tracker.update_belief(agent_id: :a1, domain: :x, content: 'v', confidence: 0.9)
+      entry = tracker.to_apollo_entries.first
+      parsed = JSON.parse(entry[:content])
+      expect(parsed).to have_key('agent_id')
+    end
+
+    it 'entry tags include theory_of_mind, agent_model, and agent_id' do
+      tracker.update_belief(agent_id: :a1, domain: :x, content: 'v', confidence: 0.9)
+      entry = tracker.to_apollo_entries.first
+      expect(entry[:tags]).to include('theory_of_mind', 'agent_model')
+      expect(entry[:tags].any? { |t| t.to_s == 'a1' }).to be true
+    end
+  end
+
+  describe '#from_apollo' do
+    let(:mock_store) do
+      double('ApolloLocal').tap do |store|
+        allow(store).to receive(:query).and_return({ success: false, results: [] })
+      end
+    end
+
+    it 'returns false when no results' do
+      expect(tracker.from_apollo(store: mock_store)).to be false
+    end
+
+    it 'populates agent_models from stored JSON' do
+      model_data = {
+        agent_id:   'agent_x',
+        beliefs:    { task: { content: 'coding', confidence: 0.9, source: 'direct_observation',
+                              updated_at: Time.now.utc.iso8601 } },
+        desires:    [],
+        intentions: []
+      }
+      content = JSON.dump(model_data)
+      allow(mock_store).to receive(:query).and_return(
+        { success: true, results: [{ content: content, tags: '["theory_of_mind","agent_model","agent_x"]' }] }
+      )
+      tracker.from_apollo(store: mock_store)
+      expect(tracker.agent_models['agent_x']).not_to be_nil
+    end
+  end
+
+  describe '#mark_clean!' do
+    it 'returns self' do
+      expect(tracker.mark_clean!).to eq(tracker)
+    end
+
+    it 'resets dirty flag' do
+      tracker.update_belief(agent_id: :a1, domain: :test, content: 'v', confidence: 0.8)
+      tracker.mark_clean!
+      expect(tracker.dirty?).to be false
+    end
+  end
+
+  describe '#pending_prediction' do
+    it 'returns nil when no predictions for agent' do
+      expect(tracker.pending_prediction(agent_id: :unknown)).to be_nil
+    end
+
+    it 'returns the most recent prediction entry' do
+      tracker.update_desire(agent_id: :a1, goal: 'help', priority: :high)
+      tracker.infer_intention(agent_id: :a1, action: :respond, confidence: :likely)
+      tracker.predict_behavior(agent_id: :a1, context: {})
+      result = tracker.pending_prediction(agent_id: :a1)
+      expect(result).to be_a(Hash)
+      expect(result[:agent_id]).to eq(:a1)
+    end
+
+    it 'returns the most recent of multiple predictions' do
+      tracker.update_desire(agent_id: :a1, goal: 'help', priority: :high)
+      tracker.infer_intention(agent_id: :a1, action: :respond, confidence: :likely)
+      2.times { tracker.predict_behavior(agent_id: :a1, context: {}) }
+      result = tracker.pending_prediction(agent_id: :a1)
+      expect(result[:predicted_at]).to eq(tracker.prediction_log.last[:predicted_at])
+    end
+  end
 end

data/spec/legion/extensions/agentic/social/theory_of_mind/runners/theory_of_mind_spec.rb

@@ -217,5 +217,51 @@ RSpec.describe Legion::Extensions::Agentic::Social::TheoryOfMind::Runners::Theor
       host.update_theory_of_mind(tick_results: {})
       expect(mental_tracker.agent_models[:a1].beliefs[:test][:confidence]).to be < initial
     end
+
+    it 'accepts human_observations kwarg without error' do
+      obs = [
+        { identity: 'esity', bond_role: :partner, channel: :cli,
+          content_type: :text, content_length: 50, direct_address: true, timestamp: Time.now.utc }
+      ]
+      expect { host.update_theory_of_mind(tick_results: {}, human_observations: obs) }.not_to raise_error
+    end
+
+    it 'builds beliefs from human_observations communication domain' do
+      obs = [
+        { identity: 'esity', bond_role: :partner, channel: :cli,
+          content_type: :text, content_length: 50, direct_address: false, timestamp: Time.now.utc }
+      ]
+      host.update_theory_of_mind(tick_results: {}, human_observations: obs)
+      model = mental_tracker.agent_models['esity']
+      expect(model).not_to be_nil
+      expect(model.beliefs[:communication]).not_to be_nil
+    end
+
+    it 'records engagement intent from direct_address observations' do
+      obs = [
+        { identity: 'alice', bond_role: :known, channel: :cli,
+          content_type: :text, content_length: 30, direct_address: true, timestamp: Time.now.utc }
+      ]
+      host.update_theory_of_mind(tick_results: {}, human_observations: obs)
+      model = mental_tracker.agent_models['alice']
+      intention = model.intentions.find { |i| i[:action] == :engage }
+      expect(intention).not_to be_nil
+    end
+
+    it 'validates pending predictions when human_observations arrive' do
+      # First seed a prediction
+      mental_tracker.update_belief(agent_id: 'bob', domain: :task, content: 'coding', confidence: 0.8)
+      mental_tracker.infer_intention(agent_id: 'bob', action: :communicate, confidence: :likely)
+      mental_tracker.predict_behavior(agent_id: 'bob', context: {})
+      initial_log_size = mental_tracker.prediction_log.size
+
+      obs = [
+        { identity: 'bob', bond_role: :known, channel: :cli,
+          content_type: :text, content_length: 20, direct_address: false, timestamp: Time.now.utc }
+      ]
+      host.update_theory_of_mind(tick_results: {}, human_observations: obs)
+      # prediction log may grow or model accuracy may change; at minimum no error
+      expect(mental_tracker.prediction_log.size).to be >= initial_log_size
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-agentic-social
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Esity