swarm_memory 2.1.2 → 2.1.4

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/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/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 workflow)
+    #
+    # @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 workflow)
+    #
+    # @return [Boolean] true if swarm snapshot
+    def swarm?
+      type == "swarm"
+    end
+
+    # Check if snapshot is for a workflow
+    #
+    # @return [Boolean] true if workflow snapshot
+    def workflow?
+      type == "workflow"
+    end
+  end
+end