swarm_sdk 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 024c305673af374d59df3e51afef83508bd787abb57465140d78d9acd5db5943
-  data.tar.gz: 8a762c50cf958e39f86a16935bc155c75fab57cfb2c334bd5e96017578ad003e
+  metadata.gz: f8643441321fcf3c24d637134d75697f61670ffa4129608c1c4d0e98571805a5
+  data.tar.gz: cb105cd387671e16eea9ebf52fbcf31a11f9ec0d6a03b7f2e45cad7721434dab
 SHA512:
-  metadata.gz: 50caef0938990e2d4c352cbf1254ed8ceea26f23cd6b3aa1490a35d2efb676de0d3b38a7735f72e6e2d490840258d6fa6c8450d5dda75e5e64ad181ad7eff97b
-  data.tar.gz: b5977d7388e96144b3a2c19e604f2e146e77bd85ca8a92f546e4accb5d3c1cbae384020189965fe27a996eada0fb62b0f5331fba5d9bd41171dbcf0be848b4bc
+  metadata.gz: f613f1d8be2c5fd00ebaaa896b54bdeb34f6537b56638706c5655d8b0ceeb942c87702be5d07be748dd194ec90c48c5e7b24d180ca6bea58714f43cd55afaf86
+  data.tar.gz: b608df1ef8b5368c4f1e84a057591103943df755706bdaba521fa56075805d6281d434968eadb4cb35edb6a4d9987e710e9b1450fde09c9ed23ed1bebe5af075

data/lib/swarm_sdk/agent/builder.rb

@@ -60,6 +60,7 @@ module SwarmSDK
         @default_permissions = {} # Set by SwarmBuilder from all_agents
         @memory_config = nil
         @shared_across_delegations = nil # nil = not set (will default to false in Definition)
+        @context_management_config = nil # Context management DSL hooks
       end
 
       # Set/get agent model
@@ -288,6 +289,56 @@ module SwarmSDK
         self
       end
 
+      # Configure context management handlers
+      #
+      # Define custom handlers for context warning thresholds (60%, 80%, 90%).
+      # Handlers receive a rich context object with message manipulation methods.
+      # When a custom handler is registered, automatic compression is disabled
+      # for that threshold, giving full control to the handler.
+      #
+      # @yield Context management DSL block
+      # @return [void]
+      #
+      # @example Basic compression at 60%
+      #   context_management do
+      #     on :warning_60 do |ctx|
+      #       ctx.compress_tool_results(keep_recent: 10)
+      #     end
+      #   end
+      #
+      # @example Multiple thresholds with different strategies
+      #   context_management do
+      #     on :warning_60 do |ctx|
+      #       ctx.compress_tool_results(keep_recent: 15, truncate_to: 500)
+      #     end
+      #
+      #     on :warning_80 do |ctx|
+      #       ctx.prune_old_messages(keep_recent: 30)
+      #       ctx.compress_tool_results(keep_recent: 5, truncate_to: 200)
+      #     end
+      #
+      #     on :warning_90 do |ctx|
+      #       ctx.log_action("emergency_pruning", remaining: ctx.tokens_remaining)
+      #       ctx.prune_old_messages(keep_recent: 15)
+      #     end
+      #   end
+      #
+      # @example Conditional logic based on metrics
+      #   context_management do
+      #     on :warning_80 do |ctx|
+      #       if ctx.usage_percentage > 85
+      #         ctx.prune_old_messages(keep_recent: 10)
+      #       else
+      #         ctx.compress_tool_results(keep_recent: 5)
+      #       end
+      #     end
+      #   end
+      def context_management(&block)
+        builder = ContextManagement::Builder.new
+        builder.instance_eval(&block)
+        @context_management_config = builder.build
+      end
+
       # Set permissions directly from hash (for YAML translation)
       #
       # This is intentionally separate from permissions() to keep the DSL clean.
@@ -411,6 +462,13 @@ module SwarmSDK
         # Convert DSL hooks to HookDefinition format
         agent_config[:hooks] = convert_hooks_to_definitions if @hooks.any?
 
+        # Merge context management hooks into agent hooks
+        if @context_management_config
+          agent_config[:hooks] ||= {}
+          agent_config[:hooks][:context_warning] ||= []
+          agent_config[:hooks][:context_warning].concat(@context_management_config)
+        end
+
         Agent::Definition.new(@name, agent_config)
       end