claude_swarm 1.0.6 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. checksums.yaml +4 -4
  2. data/.ruby-version +1 -1
  3. data/CHANGELOG.md +14 -0
  4. data/README.md +336 -1037
  5. data/docs/V1_TO_V2_MIGRATION_GUIDE.md +1120 -0
  6. data/docs/v1/README.md +1195 -0
  7. data/docs/v2/CHANGELOG.swarm_cli.md +22 -0
  8. data/docs/v2/CHANGELOG.swarm_memory.md +20 -0
  9. data/docs/v2/CHANGELOG.swarm_sdk.md +287 -10
  10. data/docs/v2/README.md +32 -6
  11. data/docs/v2/guides/complete-tutorial.md +133 -37
  12. data/docs/v2/guides/composable-swarms.md +1178 -0
  13. data/docs/v2/guides/getting-started.md +42 -1
  14. data/docs/v2/guides/snapshots.md +1498 -0
  15. data/docs/v2/reference/architecture-flow.md +5 -3
  16. data/docs/v2/reference/event_payload_structures.md +249 -12
  17. data/docs/v2/reference/execution-flow.md +1 -1
  18. data/docs/v2/reference/ruby-dsl.md +368 -22
  19. data/docs/v2/reference/yaml.md +314 -63
  20. data/examples/snapshot_demo.rb +119 -0
  21. data/examples/v2/dsl/01_basic.rb +0 -2
  22. data/examples/v2/dsl/02_core_parameters.rb +0 -2
  23. data/examples/v2/dsl/03_capabilities.rb +0 -2
  24. data/examples/v2/dsl/04_llm_parameters.rb +0 -2
  25. data/examples/v2/dsl/05_advanced_flags.rb +0 -3
  26. data/examples/v2/dsl/06_permissions.rb +0 -4
  27. data/examples/v2/dsl/07_mcp_server.rb +0 -2
  28. data/examples/v2/dsl/08_swarm_hooks.rb +0 -2
  29. data/examples/v2/dsl/09_agent_hooks.rb +0 -2
  30. data/examples/v2/dsl/10_all_agents_hooks.rb +0 -3
  31. data/examples/v2/dsl/11_delegation.rb +0 -2
  32. data/examples/v2/dsl/12_complete_integration.rb +2 -6
  33. data/examples/v2/node_context_demo.rb +1 -1
  34. data/examples/v2/node_workflow.rb +2 -4
  35. data/examples/v2/plan_and_execute.rb +157 -0
  36. data/lib/claude_swarm/configuration.rb +28 -4
  37. data/lib/claude_swarm/version.rb +1 -1
  38. data/lib/swarm_cli/formatters/human_formatter.rb +103 -0
  39. data/lib/swarm_cli/interactive_repl.rb +9 -3
  40. data/lib/swarm_cli/version.rb +1 -1
  41. data/lib/swarm_memory/core/storage_read_tracker.rb +51 -14
  42. data/lib/swarm_memory/integration/cli_registration.rb +3 -2
  43. data/lib/swarm_memory/integration/sdk_plugin.rb +11 -5
  44. data/lib/swarm_memory/tools/memory_edit.rb +2 -2
  45. data/lib/swarm_memory/tools/memory_multi_edit.rb +2 -2
  46. data/lib/swarm_memory/tools/memory_read.rb +3 -3
  47. data/lib/swarm_memory/version.rb +1 -1
  48. data/lib/swarm_memory.rb +5 -0
  49. data/lib/swarm_sdk/agent/builder.rb +33 -0
  50. data/lib/swarm_sdk/agent/chat/context_tracker.rb +33 -0
  51. data/lib/swarm_sdk/agent/chat/hook_integration.rb +49 -3
  52. data/lib/swarm_sdk/agent/chat/system_reminder_injector.rb +11 -27
  53. data/lib/swarm_sdk/agent/chat.rb +200 -51
  54. data/lib/swarm_sdk/agent/context.rb +6 -2
  55. data/lib/swarm_sdk/agent/context_manager.rb +6 -0
  56. data/lib/swarm_sdk/agent/definition.rb +14 -2
  57. data/lib/swarm_sdk/agent/llm_instrumentation_middleware.rb +180 -0
  58. data/lib/swarm_sdk/configuration.rb +387 -94
  59. data/lib/swarm_sdk/events_to_messages.rb +181 -0
  60. data/lib/swarm_sdk/log_collector.rb +31 -5
  61. data/lib/swarm_sdk/log_stream.rb +37 -8
  62. data/lib/swarm_sdk/model_aliases.json +4 -1
  63. data/lib/swarm_sdk/node/agent_config.rb +33 -8
  64. data/lib/swarm_sdk/node/builder.rb +39 -18
  65. data/lib/swarm_sdk/node_orchestrator.rb +293 -26
  66. data/lib/swarm_sdk/proc_helpers.rb +53 -0
  67. data/lib/swarm_sdk/providers/openai_with_responses.rb +22 -15
  68. data/lib/swarm_sdk/restore_result.rb +65 -0
  69. data/lib/swarm_sdk/snapshot.rb +156 -0
  70. data/lib/swarm_sdk/snapshot_from_events.rb +386 -0
  71. data/lib/swarm_sdk/state_restorer.rb +491 -0
  72. data/lib/swarm_sdk/state_snapshot.rb +369 -0
  73. data/lib/swarm_sdk/swarm/agent_initializer.rb +360 -55
  74. data/lib/swarm_sdk/swarm/all_agents_builder.rb +28 -1
  75. data/lib/swarm_sdk/swarm/builder.rb +208 -12
  76. data/lib/swarm_sdk/swarm/swarm_registry_builder.rb +67 -0
  77. data/lib/swarm_sdk/swarm/tool_configurator.rb +46 -11
  78. data/lib/swarm_sdk/swarm.rb +338 -42
  79. data/lib/swarm_sdk/swarm_loader.rb +145 -0
  80. data/lib/swarm_sdk/swarm_registry.rb +136 -0
  81. data/lib/swarm_sdk/tools/delegate.rb +92 -7
  82. data/lib/swarm_sdk/tools/read.rb +17 -5
  83. data/lib/swarm_sdk/tools/stores/read_tracker.rb +47 -12
  84. data/lib/swarm_sdk/tools/stores/scratchpad_storage.rb +45 -0
  85. data/lib/swarm_sdk/utils.rb +18 -0
  86. data/lib/swarm_sdk/validation_result.rb +33 -0
  87. data/lib/swarm_sdk/version.rb +1 -1
  88. data/lib/swarm_sdk.rb +40 -8
  89. data/swarm_cli.gemspec +1 -1
  90. data/swarm_memory.gemspec +2 -2
  91. data/swarm_sdk.gemspec +2 -2
  92. metadata +21 -13
  93. data/examples/learning-assistant/assistant.md +0 -7
  94. data/examples/learning-assistant/example-memories/concept-example.md +0 -90
  95. data/examples/learning-assistant/example-memories/experience-example.md +0 -66
  96. data/examples/learning-assistant/example-memories/fact-example.md +0 -76
  97. data/examples/learning-assistant/example-memories/memory-index.md +0 -78
  98. data/examples/learning-assistant/example-memories/skill-example.md +0 -168
  99. data/examples/learning-assistant/learning_assistant.rb +0 -34
  100. data/examples/learning-assistant/learning_assistant.yml +0 -20
  101. data/lib/swarm_sdk/mcp.rb +0 -16
  102. data/llm.v2.txt +0 -13407
  103. /data/docs/v2/guides/{MEMORY_DEFRAG_GUIDE.md → memory-defrag-guide.md} +0 -0
  104. /data/{llms.txt → llms.claude-swarm.txt} +0 -0
data/docs/v2/guides/getting-started.md CHANGED
@@ -139,6 +139,47 @@ Delegation is how agents collaborate. When an agent is configured with `delegate
139
139
 
140
140
  Delegation creates flexible collaboration patterns without rigid workflows.
141
141
 
142
+ #### Delegation Isolation Modes
143
+
144
+ When multiple agents delegate to the same target, you can control whether they share the same conversation history or get isolated instances:
145
+
146
+ **Isolated Mode (Default - Recommended):**
147
+ ```yaml
148
+ agents:
149
+ tester:
150
+ description: "Testing agent"
151
+ # shared_across_delegations: false (default)
152
+
153
+ frontend:
154
+ delegates_to: [tester] # Gets tester@frontend (isolated)
155
+
156
+ backend:
157
+ delegates_to: [tester] # Gets tester@backend (separate)
158
+ ```
159
+
160
+ Each delegator gets its own isolated instance with separate conversation history. This prevents context mixing and ensures clean boundaries.
161
+
162
+ **Shared Mode (Opt-in):**
163
+ ```yaml
164
+ agents:
165
+ database:
166
+ description: "Database coordination agent"
167
+ shared_across_delegations: true
168
+
169
+ frontend:
170
+ delegates_to: [database] # Shares same database instance
171
+
172
+ backend:
173
+ delegates_to: [database] # Shares same database instance
174
+ ```
175
+
176
+ All delegators share the same agent instance and conversation history. Use this for stateful coordination or when context sharing is beneficial.
177
+
178
+ **Key Points:**
179
+ - **Memory is always shared**: SwarmMemory and other plugin storage is shared by base agent name across all instances
180
+ - **Only conversation history differs**: Isolated mode separates conversations, but knowledge is shared
181
+ - **Choose based on use case**: Use isolated (default) for independent tasks, shared for coordination
182
+
142
183
  ### Tools
143
184
 
144
185
  Tools are functions agents call to interact with the world. SwarmSDK provides:
@@ -154,7 +195,7 @@ Tools are functions agents call to interact with the world. SwarmSDK provides:
154
195
  | **Per-Agent Memory** | MemoryWrite, MemoryRead, MemoryEdit, MemoryMultiEdit, MemoryGlob, MemoryGrep, MemoryDelete | Persistent learning and knowledge storage (opt-in) |
155
196
  | **Reasoning** | Think | Extended reasoning for complex problems |
156
197
 
157
- **Default tools**: Every agent automatically gets Read, Grep, Glob, TodoWrite, Think, WebFetch, and scratchpad tools (ScratchpadWrite, ScratchpadRead, ScratchpadList) unless you explicitly disable them with `disable_default_tools: true`.
198
+ **Default tools**: Every agent automatically gets **Read, Grep, and Glob** unless you explicitly disable them with `disable_default_tools: true`. Scratchpad tools (ScratchpadWrite, ScratchpadRead, ScratchpadList) are opt-in via `scratchpad: :enabled`.
158
199
 
159
200
  **Memory tools** are opt-in for learning agents that need persistent knowledge storage.
160
201