lex-swarm 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1b72b8c33768eb24380924cb9f33a342dd5e0e07fa1daaf151089de1d38e141e
+  data.tar.gz: 790c2c25675b41bb049410a15f21585fc361a00963d771af73752b612c2d15e9
+SHA512:
+  metadata.gz: 9ca0b32d4b9c8af87086c777c71822c32228b195e0e1c7cb825c89c9a883dd97cee6e8815e228ca4d4a8a07ce1d31813eca91e09191405f06b45c9ed0c347453
+  data.tar.gz: 6765b85f142bebdb96f537860d4984e56c762551d87da9b6fd3ab0a3b028c6f6fc3236e46b50bf445a020bf1d570c6fae3791af408c6cdc77d6ea77f68382c64

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-swarm.gemspec

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

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

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/swarm/helpers/charter'
+require 'legion/extensions/swarm/helpers/swarm_store'
+require 'legion/extensions/swarm/runners/swarm'
+
+module Legion
+  module Extensions
+    module Swarm
+      class Client
+        include Runners::Swarm
+
+        def initialize(**)
+          @swarm_store = Helpers::SwarmStore.new
+        end
+
+        private
+
+        attr_reader :swarm_store
+      end
+    end
+  end
+end

data/lib/legion/extensions/swarm/helpers/charter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Swarm
+      module Helpers
+        module Charter
+          ROLES              = %i[finder fixer validator reviewer coordinator].freeze
+          STATUSES           = %i[forming active completing disbanded failed].freeze
+          SWARM_STALE_TIMEOUT = 86_400 # 24 hours
+
+          module_function
+
+          def new_charter(name:, objective:, roles: [], max_agents: 10, timeout: 3600)
+            {
+              charter_id:   SecureRandom.uuid,
+              name:         name,
+              objective:    objective,
+              roles:        roles.empty? ? ROLES : roles,
+              max_agents:   max_agents,
+              timeout:      timeout,
+              status:       :forming,
+              agents:       [],
+              created_at:   Time.now.utc,
+              completed_at: nil
+            }
+          end
+
+          def valid_role?(role)
+            ROLES.include?(role)
+          end
+
+          def valid_status?(status)
+            STATUSES.include?(status)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/swarm/helpers/swarm_store.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Swarm
+      module Helpers
+        class SwarmStore
+          attr_reader :charters
+
+          def initialize
+            @charters = {}
+          end
+
+          def create(charter)
+            @charters[charter[:charter_id]] = charter
+            charter[:charter_id]
+          end
+
+          def get(charter_id)
+            @charters[charter_id]
+          end
+
+          def join(charter_id, agent_id:, role:)
+            charter = @charters[charter_id]
+            return :not_found unless charter
+            return :full if charter[:agents].size >= charter[:max_agents]
+            return :already_joined if charter[:agents].any? { |a| a[:agent_id] == agent_id }
+
+            charter[:agents] << { agent_id: agent_id, role: role, joined_at: Time.now.utc }
+            charter[:status] = :active if charter[:status] == :forming
+            :joined
+          end
+
+          def leave(charter_id, agent_id:)
+            charter = @charters[charter_id]
+            return :not_found unless charter
+
+            removed = charter[:agents].reject! { |a| a[:agent_id] == agent_id }
+            removed ? :left : :not_member
+          end
+
+          def complete(charter_id, outcome:)
+            charter = @charters[charter_id]
+            return nil unless charter
+
+            charter[:status] = outcome == :success ? :completing : :failed
+            charter[:completed_at] = Time.now.utc
+            charter[:outcome] = outcome
+            charter
+          end
+
+          def active_charters
+            @charters.values.select { |c| c[:status] == :active }
+          end
+
+          def count
+            @charters.size
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Swarm
+      module Runners
+        module Swarm
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_swarm(name:, objective:, roles: [], max_agents: 10, timeout: 3600, **) # rubocop:disable Metrics/ParameterLists
+            charter = Helpers::Charter.new_charter(name: name, objective: objective,
+                                                   roles: roles, max_agents: max_agents, timeout: timeout)
+            id = swarm_store.create(charter)
+            Legion::Logging.info "[swarm] created: id=#{id[0..7]} name=#{name} max=#{max_agents} roles=#{roles.join(',')}"
+            { charter_id: id, name: name, status: :forming }
+          end
+
+          def join_swarm(charter_id:, agent_id:, role:, **)
+            return { error: :invalid_role, valid: Helpers::Charter::ROLES } unless Helpers::Charter.valid_role?(role)
+
+            result = swarm_store.join(charter_id, agent_id: agent_id, role: role)
+            Legion::Logging.debug "[swarm] join: charter=#{charter_id[0..7]} agent=#{agent_id} role=#{role} result=#{result}"
+            Legion::Logging.info "[swarm] agent joined: charter=#{charter_id[0..7]} agent=#{agent_id} role=#{role}" if result == :joined
+            {
+              joined:         { joined: true, charter_id: charter_id },
+              full:           { error: :swarm_full },
+              not_found:      { error: :not_found },
+              already_joined: { error: :already_joined }
+            }[result]
+          end
+
+          def leave_swarm(charter_id:, agent_id:, **)
+            result = swarm_store.leave(charter_id, agent_id: agent_id)
+            Legion::Logging.debug "[swarm] leave: charter=#{charter_id[0..7]} agent=#{agent_id} result=#{result}"
+            Legion::Logging.info "[swarm] agent left: charter=#{charter_id[0..7]} agent=#{agent_id}" if result == :left
+            {
+              left:       { left: true },
+              not_found:  { error: :not_found },
+              not_member: { error: :not_member }
+            }[result]
+          end
+
+          def complete_swarm(charter_id:, outcome:, **)
+            result = swarm_store.complete(charter_id, outcome: outcome)
+            if result
+              Legion::Logging.info "[swarm] completed: charter=#{charter_id[0..7]} outcome=#{outcome}"
+            else
+              Legion::Logging.debug "[swarm] complete failed: charter=#{charter_id[0..7]} not found"
+            end
+            result ? { completed: true, outcome: outcome } : { error: :not_found }
+          end
+
+          def get_swarm(charter_id:, **)
+            charter = swarm_store.get(charter_id)
+            Legion::Logging.debug "[swarm] get: charter=#{charter_id[0..7]} found=#{!charter.nil?}"
+            charter ? { found: true, charter: charter } : { found: false }
+          end
+
+          def active_swarms(**)
+            charters = swarm_store.active_charters
+            Legion::Logging.debug "[swarm] active: count=#{charters.size}"
+            { charters: charters, count: charters.size }
+          end
+
+          def swarm_status(**)
+            total = swarm_store.count
+            Legion::Logging.debug "[swarm] status: total=#{total}"
+            { total: total }
+          end
+
+          def timeout_stale_swarms(**)
+            now        = Time.now.utc
+            timeout    = Helpers::Charter::SWARM_STALE_TIMEOUT
+            disbanded  = []
+            swarm_store.charters.each_value do |charter|
+              next unless %i[forming active].include?(charter[:status])
+              next unless now - charter[:created_at] > timeout
+
+              charter[:status] = :disbanded
+              disbanded << charter[:charter_id]
+            end
+            Legion::Logging.debug "[swarm] stale check: checked=#{swarm_store.charters.size} disbanded=#{disbanded.size}"
+            { checked: swarm_store.charters.size, disbanded: disbanded.size, disbanded_ids: disbanded }
+          end
+
+          private
+
+          def swarm_store
+            @swarm_store ||= Helpers::SwarmStore.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/swarm.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/swarm/version'
+require 'legion/extensions/swarm/helpers/charter'
+require 'legion/extensions/swarm/helpers/swarm_store'
+require 'legion/extensions/swarm/runners/swarm'
+
+module Legion
+  module Extensions
+    module Swarm
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Actors
+      class Every # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/swarm/actors/stale_check'
+
+RSpec.describe Legion::Extensions::Swarm::Actor::StaleCheck do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it { expect(actor.runner_class).to eq Legion::Extensions::Swarm::Runners::Swarm }
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'timeout_stale_swarms' }
+  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/swarm/client_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/swarm/client'
+
+RSpec.describe Legion::Extensions::Swarm::Client do
+  it 'responds to swarm runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_swarm)
+    expect(client).to respond_to(:join_swarm)
+    expect(client).to respond_to(:leave_swarm)
+    expect(client).to respond_to(:complete_swarm)
+    expect(client).to respond_to(:get_swarm)
+    expect(client).to respond_to(:active_swarms)
+    expect(client).to respond_to(:swarm_status)
+  end
+end

data/spec/legion/extensions/swarm/helpers/charter_spec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Swarm::Helpers::Charter do
+  describe 'constants' do
+    it 'defines ROLES as the five swarm roles' do
+      expect(described_class::ROLES).to eq(%i[finder fixer validator reviewer coordinator])
+    end
+
+    it 'defines STATUSES as the five lifecycle statuses' do
+      expect(described_class::STATUSES).to eq(%i[forming active completing disbanded failed])
+    end
+  end
+
+  describe '.new_charter' do
+    let(:charter) { described_class.new_charter(name: 'test-swarm', objective: 'fix all bugs') }
+
+    it 'returns a hash with a UUID charter_id' do
+      expect(charter[:charter_id]).to match(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/)
+    end
+
+    it 'stores the provided name' do
+      expect(charter[:name]).to eq('test-swarm')
+    end
+
+    it 'stores the provided objective' do
+      expect(charter[:objective]).to eq('fix all bugs')
+    end
+
+    it 'defaults status to :forming' do
+      expect(charter[:status]).to eq(:forming)
+    end
+
+    it 'starts with an empty agents array' do
+      expect(charter[:agents]).to eq([])
+    end
+
+    it 'sets completed_at to nil' do
+      expect(charter[:completed_at]).to be_nil
+    end
+
+    it 'records created_at as a UTC Time' do
+      before = Time.now.utc
+      c = described_class.new_charter(name: 'n', objective: 'o')
+      after = Time.now.utc
+      expect(c[:created_at]).to be_between(before, after)
+    end
+
+    it 'defaults to all ROLES when roles is empty' do
+      expect(charter[:roles]).to eq(described_class::ROLES)
+    end
+
+    it 'uses the provided roles array when non-empty' do
+      c = described_class.new_charter(name: 'n', objective: 'o', roles: %i[finder fixer])
+      expect(c[:roles]).to eq(%i[finder fixer])
+    end
+
+    it 'defaults max_agents to 10' do
+      expect(charter[:max_agents]).to eq(10)
+    end
+
+    it 'accepts a custom max_agents value' do
+      c = described_class.new_charter(name: 'n', objective: 'o', max_agents: 5)
+      expect(c[:max_agents]).to eq(5)
+    end
+
+    it 'defaults timeout to 3600' do
+      expect(charter[:timeout]).to eq(3600)
+    end
+
+    it 'accepts a custom timeout value' do
+      c = described_class.new_charter(name: 'n', objective: 'o', timeout: 7200)
+      expect(c[:timeout]).to eq(7200)
+    end
+
+    it 'generates unique charter_ids for each call' do
+      c1 = described_class.new_charter(name: 'a', objective: 'b')
+      c2 = described_class.new_charter(name: 'a', objective: 'b')
+      expect(c1[:charter_id]).not_to eq(c2[:charter_id])
+    end
+  end
+
+  describe '.valid_role?' do
+    it 'returns true for all defined ROLES' do
+      described_class::ROLES.each do |role|
+        expect(described_class.valid_role?(role)).to be true
+      end
+    end
+
+    it 'returns true for :finder' do
+      expect(described_class.valid_role?(:finder)).to be true
+    end
+
+    it 'returns true for :coordinator' do
+      expect(described_class.valid_role?(:coordinator)).to be true
+    end
+
+    it 'returns false for an unknown role' do
+      expect(described_class.valid_role?(:operator)).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_role?(nil)).to be false
+    end
+
+    it 'returns false for a string version of a valid role' do
+      expect(described_class.valid_role?('finder')).to be false
+    end
+  end
+
+  describe '.valid_status?' do
+    it 'returns true for all defined STATUSES' do
+      described_class::STATUSES.each do |status|
+        expect(described_class.valid_status?(status)).to be true
+      end
+    end
+
+    it 'returns true for :forming' do
+      expect(described_class.valid_status?(:forming)).to be true
+    end
+
+    it 'returns true for :disbanded' do
+      expect(described_class.valid_status?(:disbanded)).to be true
+    end
+
+    it 'returns false for an unknown status' do
+      expect(described_class.valid_status?(:pending)).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_status?(nil)).to be false
+    end
+
+    it 'returns false for a string version of a valid status' do
+      expect(described_class.valid_status?('active')).to be false
+    end
+  end
+end

data/spec/legion/extensions/swarm/helpers/swarm_store_spec.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Swarm::Helpers::SwarmStore do
+  let(:store) { described_class.new }
+  let(:charter_helper) { Legion::Extensions::Swarm::Helpers::Charter }
+
+  let(:charter) { charter_helper.new_charter(name: 'test-swarm', objective: 'fix bugs') }
+
+  describe '#initialize' do
+    it 'starts with an empty charters hash' do
+      expect(store.charters).to eq({})
+    end
+  end
+
+  describe '#create' do
+    it 'stores the charter by its charter_id' do
+      id = store.create(charter)
+      expect(store.charters[id]).to eq(charter)
+    end
+
+    it 'returns the charter_id' do
+      id = store.create(charter)
+      expect(id).to eq(charter[:charter_id])
+    end
+
+    it 'stores multiple charters independently' do
+      c1 = charter_helper.new_charter(name: 'swarm-a', objective: 'a')
+      c2 = charter_helper.new_charter(name: 'swarm-b', objective: 'b')
+      store.create(c1)
+      store.create(c2)
+      expect(store.count).to eq(2)
+    end
+  end
+
+  describe '#get' do
+    it 'returns the charter for a known id' do
+      store.create(charter)
+      expect(store.get(charter[:charter_id])).to eq(charter)
+    end
+
+    it 'returns nil for an unknown id' do
+      expect(store.get('nonexistent-id')).to be_nil
+    end
+  end
+
+  describe '#join' do
+    before { store.create(charter) }
+
+    it 'returns :joined when agent successfully joins' do
+      result = store.join(charter[:charter_id], agent_id: 'agent-1', role: :finder)
+      expect(result).to eq(:joined)
+    end
+
+    it 'adds the agent to the charter agents list' do
+      store.join(charter[:charter_id], agent_id: 'agent-1', role: :finder)
+      agents = store.get(charter[:charter_id])[:agents]
+      expect(agents.size).to eq(1)
+      expect(agents.first[:agent_id]).to eq('agent-1')
+    end
+
+    it 'stores the role on the joined agent record' do
+      store.join(charter[:charter_id], agent_id: 'agent-1', role: :finder)
+      expect(store.get(charter[:charter_id])[:agents].first[:role]).to eq(:finder)
+    end
+
+    it 'records joined_at as a UTC Time' do
+      before = Time.now.utc
+      store.join(charter[:charter_id], agent_id: 'agent-1', role: :finder)
+      after = Time.now.utc
+      ts = store.get(charter[:charter_id])[:agents].first[:joined_at]
+      expect(ts).to be_between(before, after)
+    end
+
+    it 'transitions status from :forming to :active on first join' do
+      store.join(charter[:charter_id], agent_id: 'agent-1', role: :finder)
+      expect(store.get(charter[:charter_id])[:status]).to eq(:active)
+    end
+
+    it 'keeps status :active when a second agent joins' do
+      store.join(charter[:charter_id], agent_id: 'agent-1', role: :finder)
+      store.join(charter[:charter_id], agent_id: 'agent-2', role: :fixer)
+      expect(store.get(charter[:charter_id])[:status]).to eq(:active)
+    end
+
+    it 'returns :not_found for unknown charter_id' do
+      result = store.join('unknown-id', agent_id: 'agent-1', role: :finder)
+      expect(result).to eq(:not_found)
+    end
+
+    it 'returns :already_joined when the agent is already a member' do
+      store.join(charter[:charter_id], agent_id: 'agent-1', role: :finder)
+      result = store.join(charter[:charter_id], agent_id: 'agent-1', role: :fixer)
+      expect(result).to eq(:already_joined)
+    end
+
+    it 'returns :full when max_agents is reached' do
+      small_charter = charter_helper.new_charter(name: 'tiny', objective: 'min', max_agents: 1)
+      store.create(small_charter)
+      store.join(small_charter[:charter_id], agent_id: 'a1', role: :finder)
+      result = store.join(small_charter[:charter_id], agent_id: 'a2', role: :fixer)
+      expect(result).to eq(:full)
+    end
+
+    it 'does not modify the charter when returning :full' do
+      small_charter = charter_helper.new_charter(name: 'tiny', objective: 'min', max_agents: 1)
+      store.create(small_charter)
+      store.join(small_charter[:charter_id], agent_id: 'a1', role: :finder)
+      store.join(small_charter[:charter_id], agent_id: 'a2', role: :fixer)
+      expect(store.get(small_charter[:charter_id])[:agents].size).to eq(1)
+    end
+  end
+
+  describe '#leave' do
+    before do
+      store.create(charter)
+      store.join(charter[:charter_id], agent_id: 'agent-1', role: :finder)
+    end
+
+    it 'returns :left when agent successfully leaves' do
+      result = store.leave(charter[:charter_id], agent_id: 'agent-1')
+      expect(result).to eq(:left)
+    end
+
+    it 'removes the agent from the agents list' do
+      store.leave(charter[:charter_id], agent_id: 'agent-1')
+      expect(store.get(charter[:charter_id])[:agents]).to be_empty
+    end
+
+    it 'returns :not_member for an agent not in the charter' do
+      result = store.leave(charter[:charter_id], agent_id: 'agent-99')
+      expect(result).to eq(:not_member)
+    end
+
+    it 'returns :not_found for unknown charter_id' do
+      result = store.leave('unknown-id', agent_id: 'agent-1')
+      expect(result).to eq(:not_found)
+    end
+
+    it 'leaves other members unaffected' do
+      store.join(charter[:charter_id], agent_id: 'agent-2', role: :fixer)
+      store.leave(charter[:charter_id], agent_id: 'agent-1')
+      agents = store.get(charter[:charter_id])[:agents]
+      expect(agents.map { |a| a[:agent_id] }).to contain_exactly('agent-2')
+    end
+  end
+
+  describe '#complete' do
+    before { store.create(charter) }
+
+    it 'sets status to :completing on success outcome' do
+      store.complete(charter[:charter_id], outcome: :success)
+      expect(store.get(charter[:charter_id])[:status]).to eq(:completing)
+    end
+
+    it 'sets status to :failed on non-success outcome' do
+      store.complete(charter[:charter_id], outcome: :failure)
+      expect(store.get(charter[:charter_id])[:status]).to eq(:failed)
+    end
+
+    it 'sets status to :failed for an arbitrary non-success outcome' do
+      store.complete(charter[:charter_id], outcome: :timeout)
+      expect(store.get(charter[:charter_id])[:status]).to eq(:failed)
+    end
+
+    it 'records completed_at as a UTC Time' do
+      before = Time.now.utc
+      store.complete(charter[:charter_id], outcome: :success)
+      after = Time.now.utc
+      ts = store.get(charter[:charter_id])[:completed_at]
+      expect(ts).to be_between(before, after)
+    end
+
+    it 'stores the outcome on the charter' do
+      store.complete(charter[:charter_id], outcome: :success)
+      expect(store.get(charter[:charter_id])[:outcome]).to eq(:success)
+    end
+
+    it 'returns the updated charter hash' do
+      result = store.complete(charter[:charter_id], outcome: :success)
+      expect(result[:charter_id]).to eq(charter[:charter_id])
+    end
+
+    it 'returns nil for unknown charter_id' do
+      expect(store.complete('unknown-id', outcome: :success)).to be_nil
+    end
+  end
+
+  describe '#active_charters' do
+    it 'returns an empty array when no charters exist' do
+      expect(store.active_charters).to eq([])
+    end
+
+    it 'excludes charters with :forming status' do
+      store.create(charter)
+      expect(store.active_charters).to eq([])
+    end
+
+    it 'returns charters with :active status' do
+      store.create(charter)
+      store.join(charter[:charter_id], agent_id: 'a1', role: :finder)
+      expect(store.active_charters.size).to eq(1)
+    end
+
+    it 'excludes charters with :completing status' do
+      store.create(charter)
+      store.join(charter[:charter_id], agent_id: 'a1', role: :finder)
+      store.complete(charter[:charter_id], outcome: :success)
+      expect(store.active_charters).to eq([])
+    end
+
+    it 'excludes charters with :failed status' do
+      store.create(charter)
+      store.join(charter[:charter_id], agent_id: 'a1', role: :finder)
+      store.complete(charter[:charter_id], outcome: :error)
+      expect(store.active_charters).to eq([])
+    end
+
+    it 'returns only the active subset among multiple charters' do
+      c1 = charter_helper.new_charter(name: 'active', objective: 'a')
+      c2 = charter_helper.new_charter(name: 'forming', objective: 'b')
+      store.create(c1)
+      store.create(c2)
+      store.join(c1[:charter_id], agent_id: 'a1', role: :finder)
+      expect(store.active_charters.size).to eq(1)
+      expect(store.active_charters.first[:charter_id]).to eq(c1[:charter_id])
+    end
+  end
+
+  describe '#count' do
+    it 'returns 0 for an empty store' do
+      expect(store.count).to eq(0)
+    end
+
+    it 'returns the number of charters stored' do
+      store.create(charter)
+      expect(store.count).to eq(1)
+    end
+
+    it 'counts all charters regardless of status' do
+      c1 = charter_helper.new_charter(name: 'a', objective: 'a')
+      c2 = charter_helper.new_charter(name: 'b', objective: 'b')
+      store.create(c1)
+      store.create(c2)
+      store.join(c1[:charter_id], agent_id: 'a1', role: :finder)
+      store.complete(c1[:charter_id], outcome: :success)
+      expect(store.count).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/swarm/runners/swarm_spec.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/swarm/client'
+
+RSpec.describe Legion::Extensions::Swarm::Runners::Swarm do
+  let(:client) { Legion::Extensions::Swarm::Client.new }
+
+  describe '#create_swarm' do
+    it 'creates a swarm charter' do
+      result = client.create_swarm(name: 'test-swarm', objective: 'fix bugs')
+      expect(result[:charter_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:status]).to eq(:forming)
+    end
+  end
+
+  describe '#join_swarm' do
+    it 'adds agent to swarm' do
+      swarm = client.create_swarm(name: 'test', objective: 'test')
+      result = client.join_swarm(charter_id: swarm[:charter_id], agent_id: 'a1', role: :finder)
+      expect(result[:joined]).to be true
+    end
+
+    it 'rejects invalid role' do
+      swarm = client.create_swarm(name: 'test', objective: 'test')
+      result = client.join_swarm(charter_id: swarm[:charter_id], agent_id: 'a1', role: :invalid)
+      expect(result[:error]).to eq(:invalid_role)
+    end
+
+    it 'prevents duplicate joins' do
+      swarm = client.create_swarm(name: 'test', objective: 'test')
+      client.join_swarm(charter_id: swarm[:charter_id], agent_id: 'a1', role: :finder)
+      result = client.join_swarm(charter_id: swarm[:charter_id], agent_id: 'a1', role: :fixer)
+      expect(result[:error]).to eq(:already_joined)
+    end
+  end
+
+  describe '#complete_swarm' do
+    it 'completes a swarm' do
+      swarm = client.create_swarm(name: 'test', objective: 'test')
+      result = client.complete_swarm(charter_id: swarm[:charter_id], outcome: :success)
+      expect(result[:completed]).to be true
+    end
+  end
+
+  describe '#active_swarms' do
+    it 'lists active swarms' do
+      swarm = client.create_swarm(name: 'test', objective: 'test')
+      client.join_swarm(charter_id: swarm[:charter_id], agent_id: 'a1', role: :finder)
+      result = client.active_swarms
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#timeout_stale_swarms' do
+    it 'returns zero disbanded when store is empty' do
+      result = client.timeout_stale_swarms
+      expect(result[:disbanded]).to eq(0)
+      expect(result[:disbanded_ids]).to eq([])
+    end
+
+    it 'does not disband a freshly created swarm' do
+      client.create_swarm(name: 'fresh', objective: 'test')
+      result = client.timeout_stale_swarms
+      expect(result[:disbanded]).to eq(0)
+    end
+
+    it 'disbands a stale forming swarm' do
+      swarm = client.create_swarm(name: 'stale', objective: 'test')
+      # backdate created_at past the timeout threshold
+      store = client.send(:swarm_store)
+      store.charters[swarm[:charter_id]][:created_at] = Time.now.utc - 90_000
+      result = client.timeout_stale_swarms
+      expect(result[:disbanded]).to eq(1)
+      expect(result[:disbanded_ids]).to include(swarm[:charter_id])
+    end
+
+    it 'reports correct checked count' do
+      client.create_swarm(name: 's1', objective: 'test')
+      client.create_swarm(name: 's2', objective: 'test')
+      result = client.timeout_stale_swarms
+      expect(result[:checked]).to eq(2)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/swarm'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: lex-swarm
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Swarm orchestration and charter system for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-swarm.gemspec
+- lib/legion/extensions/swarm.rb
+- lib/legion/extensions/swarm/actors/stale_check.rb
+- lib/legion/extensions/swarm/client.rb
+- lib/legion/extensions/swarm/helpers/charter.rb
+- lib/legion/extensions/swarm/helpers/swarm_store.rb
+- lib/legion/extensions/swarm/runners/swarm.rb
+- lib/legion/extensions/swarm/version.rb
+- spec/legion/extensions/swarm/actors/stale_check_spec.rb
+- spec/legion/extensions/swarm/client_spec.rb
+- spec/legion/extensions/swarm/helpers/charter_spec.rb
+- spec/legion/extensions/swarm/helpers/swarm_store_spec.rb
+- spec/legion/extensions/swarm/runners/swarm_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-swarm
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-swarm
+  source_code_uri: https://github.com/LegionIO/lex-swarm
+  documentation_uri: https://github.com/LegionIO/lex-swarm
+  changelog_uri: https://github.com/LegionIO/lex-swarm
+  bug_tracker_uri: https://github.com/LegionIO/lex-swarm/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Swarm
+test_files: []