swarm_memory 2.1.1 → 2.1.3

data/lib/swarm_sdk/plugin.rb

@@ -7,7 +7,32 @@ module SwarmSDK
   # Plugins are self-registering - they call SwarmSDK::PluginRegistry.register
   # when the gem is loaded.
   #
-  # @example Implementing a plugin
+  # ## Adding Custom Attributes to Agents
+  #
+  # Plugins can add custom attributes to Agent::Definition that are preserved
+  # when agents are cloned (e.g., in NodeOrchestrator). To do this:
+  #
+  # 1. Add attr_reader to Agent::Definition for your attribute
+  # 2. Parse the attribute in Agent::Definition#initialize
+  # 3. Implement serialize_config to preserve it during serialization
+  #
+  # @example Plugin with custom agent attributes
+  #   # 1. Extend Agent::Definition (in your plugin gem)
+  #   module SwarmSDK
+  #     module Agent
+  #       class Definition
+  #         attr_reader :my_custom_config
+  #
+  #         alias_method :original_initialize, :initialize
+  #         def initialize(name, config = {})
+  #           @my_custom_config = config[:my_custom_config]
+  #           original_initialize(name, config)
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   # 2. Implement plugin with serialize_config
   #   class MyPlugin < SwarmSDK::Plugin
   #     def name
   #       :my_plugin
@@ -20,9 +45,34 @@ module SwarmSDK
   #     def create_tool(tool_name, context)
   #       # Create and return tool instance
   #     end
+  #
+  #     # Preserve custom config when agents are cloned
+  #     def serialize_config(agent_definition:)
+  #       return {} unless agent_definition.my_custom_config
+  #
+  #       { my_custom_config: agent_definition.my_custom_config }
+  #     end
   #   end
   #
   #   SwarmSDK::PluginRegistry.register(MyPlugin.new)
+  #
+  # Now agents can use your custom config:
+  #
+  #   agent :researcher do
+  #     my_custom_config { option: "value" }
+  #   end
+  #
+  # And it will be preserved when NodeOrchestrator clones the agent!
+  #
+  # @example Real-world: SwarmMemory plugin
+  #   # SwarmMemory adds 'memory' attribute to agents
+  #   class SDKPlugin < SwarmSDK::Plugin
+  #     def serialize_config(agent_definition:)
+  #       return {} unless agent_definition.memory
+  #       { memory: agent_definition.memory }
+  #     end
+  #   end
+  #
   class Plugin
     # Plugin name (must be unique)
     #
@@ -143,5 +193,27 @@ module SwarmSDK
     def on_user_message(agent_name:, prompt:, is_first_message:)
       []
     end
+
+    # Contribute to agent serialization (optional)
+    #
+    # Called when Agent::Definition.to_h is invoked (e.g., for cloning agents
+    # in NodeOrchestrator). Plugins can return config keys that should be
+    # included in the serialized hash to preserve their state.
+    #
+    # This allows plugins to maintain their configuration when agents are
+    # cloned or serialized, without SwarmSDK needing to know about plugin-specific fields.
+    #
+    # @param agent_definition [Agent::Definition] Agent definition
+    # @return [Hash] Config keys to include in to_h (e.g., { memory: config })
+    #
+    # @example Memory plugin serialization
+    #   def serialize_config(agent_definition:)
+    #     return {} unless agent_definition.memory
+    #
+    #     { memory: agent_definition.memory }
+    #   end
+    def serialize_config(agent_definition:)
+      {}
+    end
   end
 end

data/lib/swarm_sdk/proc_helpers.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Helper methods for working with Procs and Lambdas
+  #
+  # Provides functionality to convert regular Proc objects into Lambdas to enable
+  # safe use of return statements in DSL blocks (like input/output transformers).
+  module ProcHelpers
+    class << self
+      # Convert a Proc to a Lambda
+      #
+      # The fundamental difference between a Proc and a Lambda is in how they handle
+      # return statements. In a Proc, return exits the enclosing method (or program),
+      # while in a Lambda, return only exits the lambda itself.
+      #
+      # This method converts a Proc to a Lambda by:
+      # 1. Converting the proc to an unbound method via define_method
+      # 2. Wrapping it in a lambda that binds and calls the method
+      # 3. In the method, return exits the method (not the original scope)
+      #
+      # This allows users to write natural control flow with return statements:
+      #
+      # @example
+      #   my_proc = proc { |x| return x * 2 if x > 0; 0 }
+      #   my_lambda = ProcHelpers.to_lambda(my_proc)
+      #   my_lambda.call(5)  # => 10 (return works safely!)
+      #
+      # @param proc [Proc] The proc to convert
+      # @return [Proc] A lambda with the same behavior but safe return semantics
+      def to_lambda(proc)
+        return proc if proc.lambda?
+
+        # Save local reference to proc so we can use it in module_exec/lambda scopes
+        source_proc = proc
+
+        # Convert proc to unbound method
+        # define_method with a block converts the block to a method, where return
+        # exits the method (not the original scope)
+        unbound_method = Module.new.module_exec do
+          instance_method(define_method(:_proc_call, &source_proc))
+        end
+
+        # Return lambda which binds our unbound method to correct receiver and calls it
+        lambda do |*args, **kwargs, &block|
+          # Bind method to the original proc's receiver (the context where it was defined)
+          # This preserves access to instance variables, local variables via closure, etc.
+          receiver = source_proc.binding.eval("self")
+          unbound_method.bind(receiver).call(*args, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/prompts/base_system_prompt.md.erb

@@ -69,139 +69,15 @@ When making changes to files, first understand the file's conventions. Mimic exi
 - When you edit something, first look at the surrounding context (especially imports/requires) to understand the choice of frameworks and libraries. Then consider how to make the given change in a way that is most consistent with existing patterns.
 - Always follow security best practices. Never introduce code that exposes or logs secrets and keys. Never commit secrets or keys to repositories.
 
-# Task Management
-
-You have access to the TodoWrite tool to help you manage and plan tasks. Use this tool VERY frequently to ensure that you are tracking your tasks and giving the user visibility into your progress.
-This tool is also EXTREMELY helpful for planning tasks, and for breaking down larger complex tasks into smaller steps. If you do not use this tool when planning, you may forget to do important tasks - and that is unacceptable.
-
-**CRITICAL WORKFLOW**: When starting a multi-step task:
-1. **FIRST**: Analyze what needs to be done (search, read files, understand scope)
-2. **SECOND**: Create a COMPLETE todo list with ALL known tasks before starting work
-3. **THIRD**: Begin executing tasks, marking them in_progress → completed as you work
-4. **ONLY add new todos** if you discover unexpected work during implementation
-
-**CRITICAL RULES FOR TODO COMPLETION**:
-- Mark EACH task as completed IMMEDIATELY after finishing it (do not batch updates)
-- You MUST complete ALL pending todos before giving your final answer to the user
-- If a task becomes irrelevant, remove it from the list or mark it completed with a note
-- NEVER leave in_progress or pending tasks when you finish responding to the user
-- Before giving your final response, verify all todos are marked completed
-
-Examples:
-
-<example>
-user: Run the build and fix any type errors
-assistant: I'll run the build first to identify all type errors, then create a complete todo list.
-
-[Runs build and finds 3 type errors in 3 different files]
-
-Now I'll create a complete todo list with all the work:
-
-[Uses TodoWrite to create full list:]
-1. Fix type error in auth.ts:45 (in_progress)
-2. Fix type error in user.ts:23 (pending)
-3. Fix type error in api.ts:67 (pending)
-4. Run build again to verify all fixes (pending)
-
-Starting with the first error in auth.ts...
-[Fixes auth.ts error]
-
-[Updates TodoWrite - marks task 1 completed, task 2 in_progress]
-
-Now fixing user.ts...
-[Fixes user.ts error]
-
-[Updates TodoWrite - marks task 2 completed, task 3 in_progress]
-
-Now fixing api.ts...
-[Fixes api.ts error]
-
-[Updates TodoWrite - marks task 3 completed, task 4 in_progress]
-
-Running build to verify...
-[Runs build - all errors fixed!]
-
-[Updates TodoWrite - marks task 4 completed]
-
-All type errors have been fixed and the build passes successfully.
-</example>
-In this example, the assistant: (1) analyzed scope first, (2) created COMPLETE todo list, (3) marked EACH task completed immediately after finishing it, (4) completed ALL tasks before giving final response.
-
-<example>
-user: Help me write a new feature that allows users to track their usage metrics and export them to various formats
-
-A: I'll help you implement a usage metrics tracking and export feature. Let me first research the codebase to understand the scope, then create a complete todo list.
-
-[Searches for existing metrics/telemetry code, examines architecture, identifies integration points]
-
-Based on my analysis, here's the complete implementation plan:
-
-[Uses TodoWrite to create full list:]
-1. Create MetricsCollector class in src/metrics/ (in_progress)
-2. Add database schema for metrics storage (pending)
-3. Implement CSV export format (pending)
-4. Implement JSON export format (pending)
-5. Create MetricsService API endpoints (pending)
-6. Add frontend UI for export (pending)
-7. Write unit tests for collectors and exporters (pending)
-8. Update documentation (pending)
-
-Now starting with the MetricsCollector class...
-[Implements MetricsCollector]
-
-[Updates TodoWrite - marks task 1 completed, task 2 in_progress]
-
-Adding database schema...
-[Creates schema]
-
-[Updates TodoWrite - marks task 2 completed, task 3 in_progress]
-
-Implementing CSV export...
-[Implements CSV exporter]
-
-[Updates TodoWrite - marks task 3 completed, task 4 in_progress]
-
-Implementing JSON export...
-[Implements JSON exporter]
-
-[Updates TodoWrite - marks task 4 completed, task 5 in_progress]
-
-Creating MetricsService API endpoints...
-[Implements API endpoints]
-
-[Updates TodoWrite - marks task 5 completed, task 6 in_progress]
-
-Adding frontend UI for export...
-[Implements UI components]
-
-[Updates TodoWrite - marks task 6 completed, task 7 in_progress]
-
-Writing unit tests...
-[Writes and runs tests - all pass]
-
-[Updates TodoWrite - marks task 7 completed, task 8 in_progress]
-
-Updating documentation...
-[Updates docs with usage examples]
-
-[Updates TodoWrite - marks task 8 completed]
-
-The metrics tracking and export feature is now complete. Users can collect metrics and export them to CSV or JSON formats through both the API and the frontend UI.
-</example>
-
 # Doing tasks
 
 The user will primarily request you perform tasks. This includes solving problems, adding new functionality, refactoring, explaining content, and more. For these tasks the following steps are recommended:
 
-- Use the TodoWrite tool to plan the task if required
 - Use the available search tools to understand the context and the user's query. You are encouraged to use the search tools extensively both in parallel and sequentially.
 - Implement the solution using all tools available to you
-- Mark each todo completed IMMEDIATELY after finishing it
 - Verify the solution if possible with tests. NEVER assume specific test framework or test script. Check the project documentation or search to determine the testing approach.
 - When you have completed a task, if there are linting or validation commands available to you, run them to ensure your work is correct. NEVER assume what these commands are - check the project documentation first.
 NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.
-- Before giving your final response: Ensure ALL todos are marked completed. NEVER leave pending or in_progress tasks.
-- IMPORTANT: Always use the TodoWrite tool to plan and track tasks throughout the conversation.
 
 # Tool usage policy
 
@@ -211,8 +87,6 @@ NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTAN
 - If the user specifies that they want you to run tools "in parallel", you MUST send a single message with multiple tool use content blocks. For example, if you need to delegate a task to multiple agents in parallel, send a single message with multiple DelegateTask tool calls.
 - Use specialized tools instead of bash commands when possible, as this provides a better user experience. For file operations, use dedicated tools: Read for reading files instead of cat/head/tail, Edit/MultiEdit for editing instead of sed/awk, and Write for creating files instead of cat with heredoc or echo redirection. Reserve bash tools exclusively for actual system commands and terminal operations that require shell execution. NEVER use bash echo or other command-line tools to communicate thoughts, explanations, or instructions to the user. Output all communication directly in your response text instead.
 
-IMPORTANT: Always use the TodoWrite tool to plan and track tasks throughout the conversation.
-
 You MUST answer concisely with fewer than 4 lines of text (not including tool use or code generation), unless user asks for detail.
 
 

data/lib/swarm_sdk/providers/openai_with_responses.rb

@@ -145,7 +145,7 @@ module SwarmSDK
       rescue NoMethodError => e
         # Catch fetch/dig errors on nil and provide better context
         if e.message.include?("undefined method") && (e.message.include?("fetch") || e.message.include?("dig"))
-          log_parse_error(e.class.name, e.message, response.body)
+          log_parse_error(e.class.name, e.message, response.body, e.backtrace)
           nil
         else
           raise
@@ -377,30 +377,36 @@ module SwarmSDK
       # This differs from chat/completions which nests under 'function':
       # { type: "function", function: { name: "tool_name", ... } }
       #
+      # RubyLLM 1.9.0+: Uses tool.params_schema for unified schema generation.
+      # This supports both old param helper and new params DSL, and includes
+      # proper JSON Schema formatting (strict, additionalProperties, etc.)
+      #
       # @param tool [RubyLLM::Tool] Tool to convert
       # @return [Hash] Tool definition in Responses API format
       def responses_tool_for(tool)
+        # Use tool.params_schema which returns a complete JSON Schema hash
+        # This works with both param helper and params DSL
+        parameters_schema = tool.params_schema || empty_parameters_schema
+
         {
           type: "function",
           name: tool.name,
           description: tool.description,
-          parameters: {
-            type: "object",
-            properties: tool.parameters.transform_values { |param| param_schema(param) },
-            required: tool.parameters.select { |_, p| p.required }.keys,
-          },
+          parameters: parameters_schema,
         }
       end
 
-      # Build parameter schema for a tool parameter
+      # Empty parameter schema for tools with no parameters
       #
-      # @param param [RubyLLM::Tool::Parameter] Parameter to convert
-      # @return [Hash] Parameter schema
-      def param_schema(param)
+      # @return [Hash] Empty JSON Schema matching OpenAI's format
+      def empty_parameters_schema
         {
-          type: param.type,
-          description: param.description,
-        }.compact
+          "type" => "object",
+          "properties" => {},
+          "required" => [],
+          "additionalProperties" => false,
+          "strict" => true,
+        }
       end
 
       # Parse Responses API response
@@ -562,7 +568,7 @@ module SwarmSDK
       # @param error_class [String] Error class name
       # @param error_message [String] Error message
       # @param response_body [Object] Response body that failed to parse
-      def log_parse_error(error_class, error_message, response_body)
+      def log_parse_error(error_class, error_message, response_body, error_backtrace = nil)
         if @agent_name
           # Emit structured JSON log through LogStream
           LogStream.emit(
@@ -570,11 +576,12 @@ module SwarmSDK
             agent: @agent_name,
             error_class: error_class,
             error_message: error_message,
+            error_backtrace: error_backtrace,
             response_body: response_body.inspect,
           )
         else
           # Fallback to RubyLLM logger if agent name not set
-          RubyLLM.logger.error("SwarmSDK: #{error_class}: #{error_message}\nResponse: #{response_body.inspect}")
+          RubyLLM.logger.error("SwarmSDK: #{error_class}: #{error_message}\nResponse: #{response_body.inspect}\nError backtrace: #{error_backtrace.join("\n")}")
         end
       end
     end

data/lib/swarm_sdk/restore_result.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Result object returned from snapshot restore operations
+  #
+  # Provides information about the restore process, including any warnings
+  # about agents or delegations that couldn't be restored due to configuration
+  # mismatches.
+  #
+  # @example Successful restore
+  #   result = swarm.restore(snapshot_data)
+  #   if result.success?
+  #     puts "All agents restored successfully"
+  #   end
+  #
+  # @example Partial restore with warnings
+  #   result = swarm.restore(snapshot_data)
+  #   if result.partial_restore?
+  #     puts result.summary
+  #     result.warnings.each do |warning|
+  #       puts "  - #{warning[:message]}"
+  #     end
+  #   end
+  class RestoreResult
+    attr_reader :warnings, :skipped_agents, :skipped_delegations
+
+    # Initialize restore result
+    #
+    # @param warnings [Array<Hash>] Warning messages with details
+    # @param skipped_agents [Array<Symbol>] Names of agents that couldn't be restored
+    # @param skipped_delegations [Array<String>] Names of delegation instances that couldn't be restored
+    def initialize(warnings:, skipped_agents:, skipped_delegations:)
+      @warnings = warnings
+      @skipped_agents = skipped_agents
+      @skipped_delegations = skipped_delegations
+    end
+
+    # Check if restore was completely successful
+    #
+    # @return [Boolean] true if all agents restored without warnings
+    def success?
+      warnings.empty?
+    end
+
+    # Check if restore was partial (some agents skipped)
+    #
+    # @return [Boolean] true if some agents were skipped
+    def partial_restore?
+      !warnings.empty?
+    end
+
+    # Get human-readable summary of restore result
+    #
+    # @return [String] Summary message
+    def summary
+      if success?
+        "Snapshot restored successfully. All agents restored."
+      else
+        "Snapshot restored with warnings. " \
+          "#{skipped_agents.size} agents skipped, " \
+          "#{skipped_delegations.size} delegation instances skipped."
+      end
+    end
+  end
+end

data/lib/swarm_sdk/result.rb

@@ -2,17 +2,17 @@
 
 module SwarmSDK
   class Result
-    attr_reader :content, :agent, :cost, :tokens, :duration, :logs, :error, :metadata
+    attr_reader :content, :agent, :duration, :logs, :error, :metadata
 
-    def initialize(content: nil, agent:, cost: 0.0, tokens: {}, duration: 0.0, logs: [], error: nil, metadata: {})
+    def initialize(content: nil, agent:, cost: nil, tokens: nil, duration: 0.0, logs: [], error: nil, metadata: {})
       @content = content
       @agent = agent
-      @cost = cost
-      @tokens = tokens
       @duration = duration
       @logs = logs
       @error = error
       @metadata = metadata
+      # Legacy parameters kept for backward compatibility but not stored
+      # Use total_cost and tokens methods instead which calculate from logs
     end
 
     def success?
@@ -23,12 +23,38 @@ module SwarmSDK
       !success?
     end
 
+    # Calculate total cost from logs
+    #
+    # Delegates to total_cost for consistency. This attribute is calculated
+    # dynamically rather than stored.
+    #
+    # @return [Float] Total cost in dollars
+    def cost
+      total_cost
+    end
+
+    # Get token breakdown from logs
+    #
+    # Returns input and output tokens from the last log entry with usage data.
+    # This attribute is calculated dynamically rather than stored.
+    #
+    # @return [Hash] Token breakdown with :input and :output keys, or empty hash if no usage data
+    def tokens
+      last_entry = @logs.reverse.find { |entry| entry.dig(:usage, :cumulative_input_tokens) }
+      return {} unless last_entry
+
+      {
+        input: last_entry.dig(:usage, :cumulative_input_tokens) || 0,
+        output: last_entry.dig(:usage, :cumulative_output_tokens) || 0,
+      }
+    end
+
     def to_h
       {
         content: @content,
         agent: @agent,
-        cost: @cost,
-        tokens: @tokens,
+        cost: cost,
+        tokens: tokens,
         duration: @duration,
         success: success?,
         error: @error&.message,

data/lib/swarm_sdk/snapshot.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Snapshot of swarm conversation state
+  #
+  # Encapsulates snapshot data with methods for serialization and deserialization.
+  # Provides a clean API for saving/loading snapshots in various formats.
+  #
+  # @example Create and save snapshot
+  #   snapshot = swarm.snapshot
+  #   snapshot.write_to_file("session.json")
+  #
+  # @example Load and restore snapshot
+  #   snapshot = SwarmSDK::Snapshot.from_file("session.json")
+  #   result = swarm.restore(snapshot)
+  #
+  # @example Convert to/from hash
+  #   hash = snapshot.to_hash
+  #   snapshot = SwarmSDK::Snapshot.from_hash(hash)
+  class Snapshot
+    attr_reader :data
+
+    # Initialize snapshot with data
+    #
+    # @param data [Hash] Snapshot data hash
+    def initialize(data)
+      @data = data
+    end
+
+    # Convert snapshot to hash
+    #
+    # @return [Hash] Snapshot data as hash
+    def to_hash
+      @data
+    end
+
+    # Convert snapshot to JSON string
+    #
+    # @param pretty [Boolean] Whether to pretty-print JSON (default: true)
+    # @return [String] JSON string
+    def to_json(pretty: true)
+      if pretty
+        JSON.pretty_generate(@data)
+      else
+        JSON.generate(@data)
+      end
+    end
+
+    # Write snapshot to file as JSON
+    #
+    # Uses atomic write pattern (write to temp file, then rename) to prevent
+    # corruption if process crashes during write.
+    #
+    # @param path [String] File path to write to
+    # @param pretty [Boolean] Whether to pretty-print JSON (default: true)
+    # @return [void]
+    def write_to_file(path, pretty: true)
+      # Atomic write: write to temp file, then rename
+      # This ensures the snapshot file is never corrupted even if process crashes
+      temp_path = "#{path}.tmp.#{Process.pid}.#{Time.now.to_i}.#{SecureRandom.hex(4)}"
+
+      File.write(temp_path, to_json(pretty: pretty))
+      File.rename(temp_path, path)
+    rescue
+      # Clean up temp file if it exists
+      File.delete(temp_path) if File.exist?(temp_path)
+      raise
+    end
+
+    class << self
+      # Create snapshot from hash
+      #
+      # @param hash [Hash] Snapshot data hash
+      # @return [Snapshot] New snapshot instance
+      def from_hash(hash)
+        new(hash)
+      end
+
+      # Create snapshot from JSON string
+      #
+      # @param json_string [String] JSON string
+      # @return [Snapshot] New snapshot instance
+      def from_json(json_string)
+        hash = JSON.parse(json_string, symbolize_names: true)
+        new(hash)
+      end
+
+      # Create snapshot from JSON file
+      #
+      # @param path [String] File path to read from
+      # @return [Snapshot] New snapshot instance
+      def from_file(path)
+        json_string = File.read(path)
+        from_json(json_string)
+      end
+    end
+
+    # Get snapshot version
+    #
+    # @return [String] Snapshot version
+    def version
+      @data[:version] || @data["version"]
+    end
+
+    # Get snapshot type (swarm or node_orchestrator)
+    #
+    # @return [String] Snapshot type
+    def type
+      @data[:type] || @data["type"]
+    end
+
+    # Get timestamp when snapshot was created
+    #
+    # @return [String] ISO8601 timestamp
+    def snapshot_at
+      @data[:snapshot_at] || @data["snapshot_at"]
+    end
+
+    # Get SwarmSDK version that created this snapshot
+    #
+    # @return [String] SwarmSDK version
+    def swarm_sdk_version
+      @data[:swarm_sdk_version] || @data["swarm_sdk_version"]
+    end
+
+    # Get agent names from snapshot
+    #
+    # @return [Array<String>] Agent names
+    def agent_names
+      agents = @data[:agents] || @data["agents"]
+      agents ? agents.keys.map(&:to_s) : []
+    end
+
+    # Get delegation instance names from snapshot
+    #
+    # @return [Array<String>] Delegation instance names
+    def delegation_instance_names
+      delegations = @data[:delegation_instances] || @data["delegation_instances"]
+      delegations ? delegations.keys.map(&:to_s) : []
+    end
+
+    # Check if snapshot is for a swarm (vs node_orchestrator)
+    #
+    # @return [Boolean] true if swarm snapshot
+    def swarm?
+      type == "swarm"
+    end
+
+    # Check if snapshot is for a node orchestrator
+    #
+    # @return [Boolean] true if node orchestrator snapshot
+    def node_orchestrator?
+      type == "node_orchestrator"
+    end
+  end
+end