lex-swarm 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b72b8c33768eb24380924cb9f33a342dd5e0e07fa1daaf151089de1d38e141e
-  data.tar.gz: 790c2c25675b41bb049410a15f21585fc361a00963d771af73752b612c2d15e9
+  metadata.gz: 578c4f78e11c1cf390624da98867d76b55274db01186715405a0e423645b99ae
+  data.tar.gz: 4584ad7f4ebe1c53eef32337404d21f930e23703f182f5f2ea835bb2c6982778
 SHA512:
-  metadata.gz: 9ca0b32d4b9c8af87086c777c71822c32228b195e0e1c7cb825c89c9a883dd97cee6e8815e228ca4d4a8a07ce1d31813eca91e09191405f06b45c9ed0c347453
-  data.tar.gz: 6765b85f142bebdb96f537860d4984e56c762551d87da9b6fd3ab0a3b028c6f6fc3236e46b50bf445a020bf1d570c6fae3791af408c6cdc77d6ea77f68382c64
+  metadata.gz: be53ef935c5ae6c6196ed41ffa15b0cbfc8ce1c708d37fccf2ecc8d75c91a511f6e2132952a7449fa58e9d56d762a8a72876a0cb9c81a0b93ce214399b168f9b
+  data.tar.gz: 5707c99712feea161e00e88a70767e74bbdd3daddb9509d99cd4b94d5236a9f246cedf109cba9a64d1077311f540163418f1f81b47f0603583334661285ad4dc

data/Gemfile

@@ -8,4 +8,4 @@ gem 'rspec', '~> 3.13'
 gem 'rubocop', '~> 1.75', require: false
 gem 'rubocop-rspec', require: false
 
-gem 'legion-gaia', path: '../../legion-gaia'
+gem 'legion-gaia'

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Swarm
+      module Actor
+        class OrphanSweeper < Legion::Extensions::Actors::Every
+          def time = 300
+          def run_now? = false
+          def use_runner? = false
+          def check_subtask? = false
+          def generate_task? = false
+
+          def action(**_opts)
+            return { swept: 0 } unless defined?(Legion::Data)
+
+            tasks = Legion::Data.connection[:tasks]
+            orphans = tasks.exclude(parent_id: nil)
+                           .exclude(status: %w[complete failed])
+                           .all
+                           .select do |t|
+              parent = tasks.where(id: t[:parent_id]).first
+              parent.nil? || %w[complete failed].include?(parent[:status])
+            end
+
+            orphans.each do |orphan|
+              tasks.where(id: orphan[:id]).update(status: 'failed')
+            end
+
+            { swept: orphans.size }
+          rescue StandardError => e
+            { swept: 0, error: e.message }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative '../helpers/workspace'
+
+module Legion
+  module Extensions
+    module Swarm
+      module Actors
+        class WorkspaceSync
+          ROUTING_PREFIX = 'swarm.workspace'
+
+          def publish_change(charter_id:, key:, operation:, value: nil, author: nil, version: nil, **) # rubocop:disable Metrics/ParameterLists
+            return { success: true, skipped: :no_transport } unless defined?(Legion::Transport)
+
+            routing_key = "#{ROUTING_PREFIX}.#{charter_id}"
+            payload     = { charter_id: charter_id, key: key, value: value,
+                            author: author, version: version, operation: operation,
+                            timestamp: Time.now.utc.to_s }
+
+            Legion::Transport.publish(routing_key: routing_key, payload: payload)
+            Legion::Logging.debug "[swarm-workspace-sync] published #{operation} #{key} to #{routing_key}"
+            { success: true, routing_key: routing_key }
+          rescue StandardError => e
+            Legion::Logging.warn "[swarm-workspace-sync] publish failed: #{e.message}"
+            { success: true, skipped: :publish_error, message: e.message }
+          end
+
+          def apply_incoming(charter_id:, key:, operation:, value: nil, author: nil, version: nil, timestamp: nil, **) # rubocop:disable Metrics/ParameterLists
+            op = operation.to_s
+            case op
+            when 'put'
+              ts      = timestamp.is_a?(String) ? Time.parse(timestamp) : (timestamp || Time.now.utc)
+              applied = workspace.apply_remote(charter_id, key: key, value: value,
+                                               author: author, version: version || 1, timestamp: ts)
+              { success: true, applied: applied }
+            when 'delete'
+              workspace.delete(charter_id, key: key)
+              { success: true, applied: true }
+            else
+              { success: false, reason: :unknown_operation, operation: op }
+            end
+          end
+
+          private
+
+          def workspace
+            @workspace ||= Helpers::Workspace.new
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,12 +3,14 @@
 require 'legion/extensions/swarm/helpers/charter'
 require 'legion/extensions/swarm/helpers/swarm_store'
 require 'legion/extensions/swarm/runners/swarm'
+require 'legion/extensions/swarm/runners/workspace'
 
 module Legion
   module Extensions
     module Swarm
       class Client
         include Runners::Swarm
+        include Runners::Workspace
 
         def initialize(**)
           @swarm_store = Helpers::SwarmStore.new

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Swarm
+      module Helpers
+        module SubAgent
+          def spawn(runner:, function:, payload:, parent_task_id:, **)
+            return { success: false, reason: :data_unavailable } unless defined?(Legion::Data::Model::Task)
+
+            parent = Legion::Data::Model::Task[parent_task_id]
+            return { success: false, reason: :parent_not_found } unless parent
+
+            new_depth = (parent.respond_to?(:depth) ? parent.depth.to_i : 0) + 1
+
+            return { success: false, reason: :depth_exceeded } if new_depth > max_depth
+            return { success: false, reason: :concurrent_exceeded } if concurrent_children_count > max_concurrent
+            return { success: false, reason: :per_parent_exceeded } if children_of(parent_task_id) > max_per_parent
+
+            if defined?(Legion::Ingress)
+              result = Legion::Ingress.run(
+                payload:       payload,
+                runner_class:  runner,
+                function:      function,
+                source:        'sub_agent',
+                generate_task: true,
+                check_subtask: false
+              )
+              { success: true, task_id: result[:task_id], depth: new_depth }
+            else
+              { success: false, reason: :ingress_unavailable }
+            end
+          rescue StandardError => e
+            { success: false, reason: :error, message: e.message }
+          end
+
+          private
+
+          def max_depth
+            Legion::Settings.dig(:swarm, :max_depth) || 3
+          rescue StandardError
+            3
+          end
+
+          def max_concurrent
+            Legion::Settings.dig(:swarm, :max_concurrent) || 20
+          rescue StandardError
+            20
+          end
+
+          def max_per_parent
+            Legion::Settings.dig(:swarm, :max_per_parent) || 10
+          rescue StandardError
+            10
+          end
+
+          def concurrent_children_count
+            return 0 unless defined?(Legion::Data)
+
+            Legion::Data.connection[:tasks]
+                        .exclude(parent_id: nil)
+                        .exclude(status: %w[complete failed])
+                        .count
+          rescue StandardError
+            0
+          end
+
+          def children_of(parent_task_id)
+            return 0 unless defined?(Legion::Data)
+
+            Legion::Data.connection[:tasks]
+                        .where(parent_id: parent_task_id)
+                        .exclude(status: %w[complete failed])
+                        .count
+          rescue StandardError
+            0
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Swarm
+      module Helpers
+        class Workspace
+          def initialize
+            @store = {}
+            @mutex = Mutex.new
+          end
+
+          def put(charter_id, key:, value:, author:)
+            @mutex.synchronize do
+              charter_store = (@store[charter_id] ||= {})
+              existing = charter_store[key]
+              version = existing ? existing[:version] + 1 : 1
+              charter_store[key] = {
+                key:       key,
+                value:     value,
+                author:    author,
+                version:   version,
+                timestamp: Time.now.utc
+              }
+            end
+          end
+
+          def get(charter_id, key:)
+            @mutex.synchronize do
+              @store.dig(charter_id, key)
+            end
+          end
+
+          def list(charter_id)
+            @mutex.synchronize do
+              (@store[charter_id] || {}).dup
+            end
+          end
+
+          def delete(charter_id, key:)
+            @mutex.synchronize do
+              charter_store = @store[charter_id]
+              return nil unless charter_store
+
+              charter_store.delete(key)
+            end
+          end
+
+          def clear_charter(charter_id)
+            @mutex.synchronize do
+              @store.delete(charter_id)
+            end
+          end
+
+          def apply_remote(charter_id, **entry)
+            key       = entry[:key]
+            value     = entry[:value]
+            author    = entry[:author]
+            version   = entry[:version]
+            timestamp = entry[:timestamp]
+
+            @mutex.synchronize do
+              charter_store = (@store[charter_id] ||= {})
+              existing = charter_store[key]
+
+              if existing.nil? || version > existing[:version] ||
+                 (version == existing[:version] && timestamp > existing[:timestamp])
+                charter_store[key] = {
+                  key:       key,
+                  value:     value,
+                  author:    author,
+                  version:   version,
+                  timestamp: timestamp
+                }
+                return true
+              end
+              false
+            end
+          end
+
+          def stats
+            @mutex.synchronize do
+              total = @store.values.sum(&:size)
+              { charter_count: @store.size, total_entries: total }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Swarm
+      module Runners
+        module SpawnChild
+          include Helpers::SubAgent if defined?(Helpers::SubAgent)
+
+          def spawn_child(runner:, function:, payload:, parent_task_id:, **)
+            spawn(runner: runner, function: function, payload: payload, parent_task_id: parent_task_id)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/workspace'
+
+module Legion
+  module Extensions
+    module Swarm
+      module Runners
+        module Workspace
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def workspace_put(charter_id:, key:, value:, author:, **)
+            entry = workspace.put(charter_id, key: key, value: value, author: author)
+            Legion::Logging.debug "[swarm-workspace] put: charter=#{charter_id[0..7]} key=#{key} v=#{entry[:version]}"
+            { success: true, key: key, version: entry[:version], charter_id: charter_id }
+          end
+
+          def workspace_get(charter_id:, key:, **)
+            entry = workspace.get(charter_id, key: key)
+            if entry
+              { success: true, entry: entry }
+            else
+              { success: false, reason: :not_found, key: key, charter_id: charter_id }
+            end
+          end
+
+          def workspace_list(charter_id:, **)
+            entries = workspace.list(charter_id)
+            { success: true, entries: entries, count: entries.size }
+          end
+
+          def workspace_delete(charter_id:, key:, **)
+            removed = workspace.delete(charter_id, key: key)
+            if removed
+              Legion::Logging.debug "[swarm-workspace] delete: charter=#{charter_id[0..7]} key=#{key}"
+              { success: true, key: key, charter_id: charter_id }
+            else
+              { success: false, reason: :not_found, key: key, charter_id: charter_id }
+            end
+          end
+
+          def workspace_clear(charter_id:, **)
+            workspace.clear_charter(charter_id)
+            Legion::Logging.debug "[swarm-workspace] clear: charter=#{charter_id[0..7]}"
+            { success: true, charter_id: charter_id }
+          end
+
+          def workspace_stats(**)
+            workspace.stats.merge(success: true)
+          end
+
+          private
+
+          def workspace
+            @workspace ||= Helpers::Workspace.new
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Swarm
-      VERSION = '0.1.1'
+      VERSION = '0.2.0'
     end
   end
 end

data/lib/legion/extensions/swarm.rb

@@ -3,7 +3,11 @@
 require 'legion/extensions/swarm/version'
 require 'legion/extensions/swarm/helpers/charter'
 require 'legion/extensions/swarm/helpers/swarm_store'
+require 'legion/extensions/swarm/helpers/sub_agent'
+require 'legion/extensions/swarm/helpers/workspace'
 require 'legion/extensions/swarm/runners/swarm'
+require 'legion/extensions/swarm/runners/spawn_child'
+require 'legion/extensions/swarm/runners/workspace'
 
 module Legion
   module Extensions

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Actors
+      unless defined?(Every)
+        class Every # rubocop:disable Lint/EmptyClass
+        end
+      end
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/swarm/actors/orphan_sweeper'
+
+RSpec.describe Legion::Extensions::Swarm::Actor::OrphanSweeper do
+  subject(:actor) { described_class.new }
+
+  describe '#time' do
+    it 'returns 300 seconds' do
+      expect(actor.time).to eq(300)
+    end
+  end
+
+  describe '#run_now?' do
+    it 'returns false' do
+      expect(actor.run_now?).to be false
+    end
+  end
+
+  describe '#action' do
+    context 'when Legion::Data is not available' do
+      it 'returns zero swept' do
+        result = actor.action
+        expect(result[:swept]).to eq(0)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require_relative '../../../../../lib/legion/extensions/swarm/actors/workspace_sync'
+
+RSpec.describe Legion::Extensions::Swarm::Actors::WorkspaceSync do
+  subject(:actor) { described_class.allocate }
+
+  describe '#publish_change' do
+    it 'returns skipped when transport is not available' do
+      result = actor.publish_change(charter_id: 'c1', key: 'k', value: 'v',
+                                    author: 'a', version: 1, operation: :put)
+      expect(result[:success]).to be true
+      expect(result[:skipped]).to eq(:no_transport)
+    end
+  end
+
+  describe '#apply_incoming' do
+    let(:workspace) { Legion::Extensions::Swarm::Helpers::Workspace.new }
+
+    before { actor.instance_variable_set(:@workspace, workspace) }
+
+    it 'applies a remote put operation' do
+      result = actor.apply_incoming(
+        charter_id: 'c1', key: 'shared', value: 'remote-data',
+        author: 'remote-agent', version: 1, timestamp: Time.now.utc.to_s, operation: 'put'
+      )
+      expect(result[:success]).to be true
+      expect(result[:applied]).to be true
+      expect(workspace.get('c1', key: 'shared')[:value]).to eq('remote-data')
+    end
+
+    it 'applies a remote delete operation' do
+      workspace.put('c1', key: 'doomed', value: 'bye', author: 'local')
+      result = actor.apply_incoming(
+        charter_id: 'c1', key: 'doomed', operation: 'delete'
+      )
+      expect(result[:success]).to be true
+      expect(workspace.get('c1', key: 'doomed')).to be_nil
+    end
+
+    it 'rejects unknown operations' do
+      result = actor.apply_incoming(charter_id: 'c1', key: 'x', operation: 'explode')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:unknown_operation)
+    end
+  end
+end

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

@@ -13,4 +13,24 @@ RSpec.describe Legion::Extensions::Swarm::Client do
     expect(client).to respond_to(:active_swarms)
     expect(client).to respond_to(:swarm_status)
   end
+
+  it 'responds to workspace runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:workspace_put)
+    expect(client).to respond_to(:workspace_get)
+    expect(client).to respond_to(:workspace_list)
+    expect(client).to respond_to(:workspace_delete)
+    expect(client).to respond_to(:workspace_clear)
+    expect(client).to respond_to(:workspace_stats)
+  end
+
+  describe '#workspace_put and #workspace_get' do
+    it 'stores and retrieves workspace entries via client' do
+      client = described_class.new
+      client.workspace_put(charter_id: 'c1', key: 'data', value: 'hello', author: 'a')
+      result = client.workspace_get(charter_id: 'c1', key: 'data')
+      expect(result[:success]).to be true
+      expect(result[:entry][:value]).to eq('hello')
+    end
+  end
 end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Swarm::Helpers::SubAgent do
+  let(:helper_instance) { Class.new { include Legion::Extensions::Swarm::Helpers::SubAgent }.new }
+
+  before do
+    stub_const('Legion::Settings', Module.new do
+      def self.dig(*keys)
+        case keys
+        when %i[swarm max_depth] then 3
+        when %i[swarm max_concurrent] then 20
+        when %i[swarm max_per_parent] then 10
+        end
+      end
+    end)
+  end
+
+  describe '#max_depth' do
+    it 'returns configured max depth' do
+      expect(helper_instance.send(:max_depth)).to eq(3)
+    end
+  end
+
+  describe '#max_concurrent' do
+    it 'returns configured max concurrent' do
+      expect(helper_instance.send(:max_concurrent)).to eq(20)
+    end
+  end
+
+  describe '#max_per_parent' do
+    it 'returns configured max per parent' do
+      expect(helper_instance.send(:max_per_parent)).to eq(10)
+    end
+  end
+
+  describe '#spawn' do
+    context 'when legion-data is not available' do
+      it 'returns failure' do
+        result = helper_instance.spawn(runner: 'SomeRunner', function: 'do_thing',
+                                       payload: {}, parent_task_id: 1)
+        expect(result[:success]).to be false
+        expect(result[:reason]).to eq(:data_unavailable)
+      end
+    end
+
+    context 'when depth would be exceeded' do
+      let(:parent_task) { double('Task', depth: 3, id: 1) }
+
+      before do
+        pt = parent_task
+        task_model = Class.new do
+          define_method(:[]) { |_id| pt }
+        end.new
+        stub_const('Legion::Data::Model::Task', task_model)
+      end
+
+      it 'returns depth_exceeded' do
+        result = helper_instance.spawn(runner: 'SomeRunner', function: 'do_thing',
+                                       payload: {}, parent_task_id: 1)
+        expect(result[:success]).to be false
+        expect(result[:reason]).to eq(:depth_exceeded)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Swarm::Helpers::Workspace do
+  subject(:workspace) { described_class.new }
+
+  let(:charter_id) { 'charter-abc' }
+
+  describe '#put and #get' do
+    it 'stores and retrieves an entry' do
+      workspace.put(charter_id, key: 'findings', value: { data: [1, 2, 3] }, author: 'agent-a')
+      entry = workspace.get(charter_id, key: 'findings')
+      expect(entry[:value]).to eq({ data: [1, 2, 3] })
+      expect(entry[:author]).to eq('agent-a')
+      expect(entry[:version]).to eq(1)
+    end
+
+    it 'increments version on overwrite' do
+      workspace.put(charter_id, key: 'result', value: 'v1', author: 'agent-a')
+      workspace.put(charter_id, key: 'result', value: 'v2', author: 'agent-b')
+      entry = workspace.get(charter_id, key: 'result')
+      expect(entry[:value]).to eq('v2')
+      expect(entry[:author]).to eq('agent-b')
+      expect(entry[:version]).to eq(2)
+    end
+
+    it 'returns nil for missing key' do
+      expect(workspace.get(charter_id, key: 'nope')).to be_nil
+    end
+
+    it 'returns nil for missing charter' do
+      expect(workspace.get('nonexistent', key: 'x')).to be_nil
+    end
+  end
+
+  describe '#list' do
+    it 'returns all entries for a charter' do
+      workspace.put(charter_id, key: 'a', value: 1, author: 'x')
+      workspace.put(charter_id, key: 'b', value: 2, author: 'y')
+      entries = workspace.list(charter_id)
+      expect(entries.keys).to contain_exactly('a', 'b')
+    end
+
+    it 'returns empty hash for unknown charter' do
+      expect(workspace.list('unknown')).to eq({})
+    end
+  end
+
+  describe '#delete' do
+    it 'removes an entry and returns it' do
+      workspace.put(charter_id, key: 'temp', value: 'data', author: 'a')
+      removed = workspace.delete(charter_id, key: 'temp')
+      expect(removed[:value]).to eq('data')
+      expect(workspace.get(charter_id, key: 'temp')).to be_nil
+    end
+
+    it 'returns nil when key does not exist' do
+      expect(workspace.delete(charter_id, key: 'nope')).to be_nil
+    end
+  end
+
+  describe '#clear_charter' do
+    it 'removes all entries for a charter' do
+      workspace.put(charter_id, key: 'a', value: 1, author: 'x')
+      workspace.put(charter_id, key: 'b', value: 2, author: 'x')
+      workspace.clear_charter(charter_id)
+      expect(workspace.list(charter_id)).to eq({})
+    end
+  end
+
+  describe '#apply_remote' do
+    it 'applies a remote put when version is higher' do
+      workspace.put(charter_id, key: 'shared', value: 'local', author: 'a')
+      workspace.apply_remote(charter_id, key: 'shared', value: 'remote', author: 'b',
+                             version: 5, timestamp: Time.now.utc)
+      expect(workspace.get(charter_id, key: 'shared')[:value]).to eq('remote')
+      expect(workspace.get(charter_id, key: 'shared')[:version]).to eq(5)
+    end
+
+    it 'ignores remote put when version is lower' do
+      workspace.put(charter_id, key: 'shared', value: 'local', author: 'a')
+      workspace.put(charter_id, key: 'shared', value: 'local2', author: 'a')
+      workspace.apply_remote(charter_id, key: 'shared', value: 'stale', author: 'b',
+                             version: 1, timestamp: Time.now.utc)
+      expect(workspace.get(charter_id, key: 'shared')[:value]).to eq('local2')
+    end
+
+    it 'uses timestamp to break version ties' do
+      workspace.put(charter_id, key: 'tie', value: 'old', author: 'a')
+      later = Time.now.utc + 1
+      workspace.apply_remote(charter_id, key: 'tie', value: 'newer', author: 'b',
+                             version: 1, timestamp: later)
+      expect(workspace.get(charter_id, key: 'tie')[:value]).to eq('newer')
+    end
+  end
+
+  describe '#stats' do
+    it 'returns charter count and total entries' do
+      workspace.put('c1', key: 'a', value: 1, author: 'x')
+      workspace.put('c1', key: 'b', value: 2, author: 'x')
+      workspace.put('c2', key: 'c', value: 3, author: 'y')
+      stats = workspace.stats
+      expect(stats[:charter_count]).to eq(2)
+      expect(stats[:total_entries]).to eq(3)
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Swarm::Runners::SpawnChild do
+  let(:runner_instance) { Class.new { include Legion::Extensions::Swarm::Runners::SpawnChild }.new }
+
+  before do
+    stub_const('Legion::Settings', Module.new do
+      def self.dig(*_keys) = nil
+    end)
+  end
+
+  describe '#spawn_child' do
+    it 'delegates to SubAgent.spawn and returns result' do
+      result = runner_instance.spawn_child(runner: 'R', function: 'f',
+                                           payload: {}, parent_task_id: 1)
+      expect(result).to be_a(Hash)
+      expect(result).to have_key(:success)
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Swarm::Runners::Workspace do
+  subject(:runner) { Object.new.extend(described_class) }
+
+  let(:charter_id) { 'charter-123' }
+
+  before { runner.instance_variable_set(:@workspace, nil) }
+
+  describe '#workspace_put' do
+    it 'stores a value and returns success' do
+      result = runner.workspace_put(charter_id: charter_id, key: 'notes', value: 'hello', author: 'agent-a')
+      expect(result[:success]).to be true
+      expect(result[:key]).to eq('notes')
+      expect(result[:version]).to eq(1)
+    end
+  end
+
+  describe '#workspace_get' do
+    it 'retrieves a stored value' do
+      runner.workspace_put(charter_id: charter_id, key: 'data', value: [1, 2], author: 'a')
+      result = runner.workspace_get(charter_id: charter_id, key: 'data')
+      expect(result[:success]).to be true
+      expect(result[:entry][:value]).to eq([1, 2])
+    end
+
+    it 'returns not_found for missing key' do
+      result = runner.workspace_get(charter_id: charter_id, key: 'nope')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#workspace_list' do
+    it 'lists all entries for a charter' do
+      runner.workspace_put(charter_id: charter_id, key: 'a', value: 1, author: 'x')
+      runner.workspace_put(charter_id: charter_id, key: 'b', value: 2, author: 'x')
+      result = runner.workspace_list(charter_id: charter_id)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#workspace_delete' do
+    it 'deletes an entry and returns success' do
+      runner.workspace_put(charter_id: charter_id, key: 'temp', value: 'x', author: 'a')
+      result = runner.workspace_delete(charter_id: charter_id, key: 'temp')
+      expect(result[:success]).to be true
+    end
+
+    it 'returns not_found for missing key' do
+      result = runner.workspace_delete(charter_id: charter_id, key: 'nope')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#workspace_clear' do
+    it 'clears all entries for a charter' do
+      runner.workspace_put(charter_id: charter_id, key: 'a', value: 1, author: 'x')
+      result = runner.workspace_clear(charter_id: charter_id)
+      expect(result[:success]).to be true
+      expect(runner.workspace_list(charter_id: charter_id)[:count]).to eq(0)
+    end
+  end
+
+  describe '#workspace_stats' do
+    it 'returns workspace statistics' do
+      runner.workspace_put(charter_id: 'c1', key: 'a', value: 1, author: 'x')
+      runner.workspace_put(charter_id: 'c2', key: 'b', value: 2, author: 'y')
+      result = runner.workspace_stats
+      expect(result[:success]).to be true
+      expect(result[:charter_count]).to eq(2)
+      expect(result[:total_entries]).to eq(2)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Esity
@@ -33,17 +33,29 @@ files:
 - Gemfile
 - lex-swarm.gemspec
 - lib/legion/extensions/swarm.rb
+- lib/legion/extensions/swarm/actors/orphan_sweeper.rb
 - lib/legion/extensions/swarm/actors/stale_check.rb
+- lib/legion/extensions/swarm/actors/workspace_sync.rb
 - lib/legion/extensions/swarm/client.rb
 - lib/legion/extensions/swarm/helpers/charter.rb
+- lib/legion/extensions/swarm/helpers/sub_agent.rb
 - lib/legion/extensions/swarm/helpers/swarm_store.rb
+- lib/legion/extensions/swarm/helpers/workspace.rb
+- lib/legion/extensions/swarm/runners/spawn_child.rb
 - lib/legion/extensions/swarm/runners/swarm.rb
+- lib/legion/extensions/swarm/runners/workspace.rb
 - lib/legion/extensions/swarm/version.rb
+- spec/legion/extensions/swarm/actors/orphan_sweeper_spec.rb
 - spec/legion/extensions/swarm/actors/stale_check_spec.rb
+- spec/legion/extensions/swarm/actors/workspace_sync_spec.rb
 - spec/legion/extensions/swarm/client_spec.rb
 - spec/legion/extensions/swarm/helpers/charter_spec.rb
+- spec/legion/extensions/swarm/helpers/sub_agent_spec.rb
 - spec/legion/extensions/swarm/helpers/swarm_store_spec.rb
+- spec/legion/extensions/swarm/helpers/workspace_spec.rb
+- spec/legion/extensions/swarm/runners/spawn_child_spec.rb
 - spec/legion/extensions/swarm/runners/swarm_spec.rb
+- spec/legion/extensions/swarm/runners/workspace_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/LegionIO/lex-swarm
 licenses: