claude_swarm 1.0.9 → 1.0.11

data/lib/swarm_sdk/plugin.rb

@@ -10,7 +10,7 @@ module SwarmSDK
   # ## 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:
+  # when agents are cloned (e.g., in Workflow). To do this:
   #
   # 1. Add attr_reader to Agent::Definition for your attribute
   # 2. Parse the attribute in Agent::Definition#initialize
@@ -62,7 +62,7 @@ module SwarmSDK
   #     my_custom_config { option: "value" }
   #   end
   #
-  # And it will be preserved when NodeOrchestrator clones the agent!
+  # And it will be preserved when Workflow clones the agent!
   #
   # @example Real-world: SwarmMemory plugin
   #   # SwarmMemory adds 'memory' attribute to agents
@@ -139,11 +139,11 @@ module SwarmSDK
       []
     end
 
-    # Agent storage enabled for this agent? (optional)
+    # Check if memory is configured for this agent (optional)
     #
     # @param agent_definition [Agent::Definition] Agent definition
     # @return [Boolean] True if storage should be created
-    def storage_enabled?(agent_definition)
+    def memory_configured?(agent_definition)
       false
     end
 
@@ -197,7 +197,7 @@ module SwarmSDK
     # 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
+    # in Workflow). 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
@@ -215,5 +215,95 @@ module SwarmSDK
     def serialize_config(agent_definition:)
       {}
     end
+
+    # Snapshot plugin-specific state for an agent
+    #
+    # Called during state snapshot creation (e.g., session persistence).
+    # Return any state your plugin needs to persist for this agent.
+    # The returned hash will be JSON serialized.
+    #
+    # @param agent_name [Symbol] Agent identifier
+    # @return [Hash] Plugin-specific state (empty hash if nothing to snapshot)
+    #
+    # @example Memory read tracking
+    #   def snapshot_agent_state(agent_name)
+    #     entries = StorageReadTracker.get_read_entries(agent_name)
+    #     return {} if entries.empty?
+    #
+    #     { read_entries: entries }
+    #   end
+    def snapshot_agent_state(agent_name)
+      {}
+    end
+
+    # Restore plugin-specific state for an agent
+    #
+    # Called during state restoration. Restore any persisted state.
+    # This method is idempotent - calling it multiple times with
+    # the same state should produce the same result.
+    #
+    # @param agent_name [Symbol] Agent identifier
+    # @param state [Hash] Previously snapshotted state (with symbol keys)
+    # @return [void]
+    #
+    # @example Memory read tracking
+    #   def restore_agent_state(agent_name, state)
+    #     entries = state[:read_entries] || state["read_entries"]
+    #     return unless entries
+    #
+    #     StorageReadTracker.restore_read_entries(agent_name, entries)
+    #   end
+    def restore_agent_state(agent_name, state)
+      # Override if needed
+    end
+
+    # Get digest for a tool result (e.g., file hash, memory entry hash)
+    #
+    # Called during tool result metadata collection. Returns a digest
+    # that can be used to detect if the resource has changed since
+    # it was last read. This enables change detection hooks.
+    #
+    # @param agent_name [Symbol] Agent identifier
+    # @param tool_name [String] Name of the tool (e.g., "MemoryRead")
+    # @param path [String] Path or identifier of the resource
+    # @return [String, nil] Digest string or nil if not tracked by this plugin
+    #
+    # @example Memory read tracking
+    #   def get_tool_result_digest(agent_name:, tool_name:, path:)
+    #     return unless tool_name == "MemoryRead"
+    #
+    #     StorageReadTracker.get_read_entries(agent_name)[path]
+    #   end
+    def get_tool_result_digest(agent_name:, tool_name:, path:)
+      nil
+    end
+
+    # Translate YAML configuration into DSL calls
+    #
+    # Called during YAML-to-DSL translation. Plugins can translate their
+    # specific YAML configuration keys into DSL method calls on the builder.
+    # This allows SDK to remain plugin-agnostic while plugins can add
+    # YAML configuration support.
+    #
+    # @param builder [Agent::Builder] Builder instance (self in DSL context)
+    # @param agent_config [Hash] Full agent config from YAML
+    # @return [void]
+    #
+    # @example Memory plugin YAML translation
+    #   def translate_yaml_config(builder, agent_config)
+    #     memory_config = agent_config[:memory]
+    #     return unless memory_config
+    #
+    #     builder.instance_eval do
+    #       memory do
+    #         directory(memory_config[:directory])
+    #         adapter(memory_config[:adapter]) if memory_config[:adapter]
+    #         mode(memory_config[:mode]) if memory_config[:mode]
+    #       end
+    #     end
+    #   end
+    def translate_yaml_config(builder, agent_config)
+      # Override if plugin needs YAML configuration support
+    end
   end
 end

data/lib/swarm_sdk/result.rb

@@ -109,6 +109,58 @@ module SwarmSDK
       @logs.map { |entry| entry[:agent] }.compact.uniq.map(&:to_sym)
     end
 
+    # Get per-agent usage breakdown from logs
+    #
+    # Aggregates context usage, tokens, and cost for each agent from their
+    # final agent_stop or agent_step events. Each agent's entry includes:
+    # - input_tokens, output_tokens, total_tokens
+    # - context_limit, usage_percentage, tokens_remaining
+    # - input_cost, output_cost, total_cost
+    #
+    # @return [Hash{Symbol => Hash}] Per-agent usage breakdown
+    #
+    # @example
+    #   result.per_agent_usage[:backend]
+    #   # => {
+    #   #   input_tokens: 15000,
+    #   #   output_tokens: 5000,
+    #   #   total_tokens: 20000,
+    #   #   context_limit: 200000,
+    #   #   usage_percentage: "10.0%",
+    #   #   tokens_remaining: 180000,
+    #   #   input_cost: 0.045,
+    #   #   output_cost: 0.075,
+    #   #   total_cost: 0.12
+    #   # }
+    def per_agent_usage
+      # Find the last usage entry for each agent
+      agent_entries = {}
+
+      @logs.each do |entry|
+        next unless entry[:usage] && entry[:agent]
+        next unless entry[:type] == "agent_step" || entry[:type] == "agent_stop"
+
+        agent_name = entry[:agent].to_sym
+        agent_entries[agent_name] = entry[:usage]
+      end
+
+      # Build breakdown from final usage entries
+      agent_entries.transform_values do |usage|
+        {
+          input_tokens: usage[:cumulative_input_tokens] || 0,
+          output_tokens: usage[:cumulative_output_tokens] || 0,
+          total_tokens: usage[:cumulative_total_tokens] || 0,
+          cached_tokens: usage[:cumulative_cached_tokens] || 0,
+          context_limit: usage[:context_limit],
+          usage_percentage: usage[:tokens_used_percentage],
+          tokens_remaining: usage[:tokens_remaining],
+          input_cost: usage[:input_cost] || 0.0,
+          output_cost: usage[:output_cost] || 0.0,
+          total_cost: usage[:total_cost] || 0.0,
+        }
+      end
+    end
+
     # Count total LLM requests made
     # Each LLM API call produces either agent_step (tool calls) or agent_stop (final answer)
     def llm_requests

data/lib/swarm_sdk/snapshot.rb

@@ -102,7 +102,7 @@ module SwarmSDK
       @data[:version] || @data["version"]
     end
 
-    # Get snapshot type (swarm or node_orchestrator)
+    # Get snapshot type (swarm or workflow)
     #
     # @return [String] Snapshot type
     def type
@@ -139,18 +139,18 @@ module SwarmSDK
       delegations ? delegations.keys.map(&:to_s) : []
     end
 
-    # Check if snapshot is for a swarm (vs node_orchestrator)
+    # 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 node orchestrator
+    # Check if snapshot is for a workflow
     #
-    # @return [Boolean] true if node orchestrator snapshot
-    def node_orchestrator?
-      type == "node_orchestrator"
+    # @return [Boolean] true if workflow snapshot
+    def workflow?
+      type == "workflow"
     end
   end
 end

data/lib/swarm_sdk/snapshot_from_events.rb

@@ -69,16 +69,17 @@ module SwarmSDK
     # @return [Hash] StateSnapshot hash
     def reconstruct
       {
-        version: "1.0.0",
+        version: "2.1.0",
         type: "swarm",
         snapshot_at: @events.last&.fetch(:timestamp, Time.now.utc.iso8601),
         swarm_sdk_version: SwarmSDK::VERSION,
-        swarm: reconstruct_swarm_metadata,
+        metadata: reconstruct_swarm_metadata,
         agents: reconstruct_all_agents,
         delegation_instances: reconstruct_all_delegations,
         scratchpad: reconstruct_scratchpad,
         read_tracking: reconstruct_read_tracking,
         memory_read_tracking: reconstruct_memory_read_tracking,
+        plugin_states: reconstruct_plugin_states,
       }
     end
 
@@ -363,6 +364,16 @@ module SwarmSDK
       tracking
     end
 
+    # Reconstruct plugin states
+    #
+    # Plugin states cannot be fully reconstructed from events alone as they
+    # contain internal plugin data. Returns empty hash for compatibility.
+    #
+    # @return [Hash] Empty plugin states hash
+    def reconstruct_plugin_states
+      {}
+    end
+
     # Parse timestamp string to Time object
     #
     # @param timestamp [String, nil] ISO 8601 timestamp