Swarms — कोड मोड में एजेंट फ़ैन-आउट और ऑर्केस्ट्रेशन

स्थिति: जारी — docs/tools/swarm.md द्वारा प्रतिस्थापित। यह दस्तावेज़ कार्यान्वयन डिज़ाइन रिकॉर्ड के रूप में बना हुआ है।

1. क्या और क्यों

swarm कई सबएजेंट का समूह है, जिन्हें कोड-मोड स्क्रिप्ट से नियतात्मक रूप से ऑर्केस्ट्रेट किया जाता है: N रीडर में फ़ैन-आउट करना, निष्कर्षों को प्रतिकूल ढंग से सत्यापित करना, स्टेटफ़ुल प्राथमिकताकर्ता के माध्यम से संश्लेषित करना, निर्णय गेट पर लूप करना। नियंत्रण प्रवाह (Promise.all, while, if) ही ऑर्केस्ट्रेशन है — जानबूझकर कोई ग्राफ़ DSL, कोई नया मोड और कोई नई शीर्ष-स्तरीय टूल सतह नहीं है।

OpenClaw कोड मोड (QuickJS-WASI, स्नैपशॉट/रिज़्यूम, ब्रिज अनुरोध) इसका आधार है। पार्क की गई ब्रिज कॉल VM स्नैपशॉट और Gateway रीस्टार्ट के बाद भी बनी रहती है और ठीक वहीं से फिर शुरू होती है जहाँ रुकी थी — यह जर्नल-रीप्ले डिज़ाइन से अधिक सशक्त है और स्क्रिप्ट पर नियतात्मकता की कोई बाधा नहीं लगाती।

नामकरण: उत्पाद/दस्तावेज़ का नाम Swarm है। कोड पहचानकर्ता यथावत रहते हैं: agents.* गेस्ट API, tools.swarm कॉन्फ़िगरेशन, swarm समूह कॉलम।

2. निर्णय (मेंटेनर, 2026-07-17)

• लागत: कॉन्फ़िगरेशन सीमाएँ लागू; प्रति-swarm टोकन बजट वैकल्पिक। कोई अनिवार्य बजट नहीं।
• स्वीकृतियाँ: चाइल्ड विफलता पर बंद / गैर-संवादात्मक रूप में चलते हैं। स्वीकृति की आवश्यकता वाली कार्रवाइयाँ अस्वीकार की जाती हैं; अस्वीकृति चाइल्ड परिणाम में रिपोर्ट होती है; स्क्रिप्ट निर्णय लेती है। फ़ैन-आउट से ऑपरेटर प्रॉम्प्ट की बाढ़ नहीं आती।
• v1 केवल मॉडल द्वारा लिखी गई तदर्थ स्क्रिप्ट के लिए है। सहेजे गए/नामित वर्कफ़्लो, CLI/Cron प्रवेश: बाद में (Cron के लिए हेडलेस कोड मोड पहले से मौजूद है)।
• चाइल्ड पहचान: डिफ़ॉल्ट रूप से tools.swarm.defaultAgentId कॉन्फ़िगरेशन के माध्यम से समर्पित वर्कर एजेंट (मौजूदा सबएजेंट लक्ष्य अनुमति-सूची के विरुद्ध सत्यापित); प्रति-स्पॉन agentId ओवरराइड। कोर में कोई बंडल किया हुआ एजेंट आईडी जारी नहीं होता; दस्तावेज़ एक हल्के worker एजेंट कॉन्फ़िगरेशन की अनुशंसा करते हैं।
• Codex स्रोत में कोई बदलाव नहीं। Codex हार्नेस स्पॉन/वेट मुहावरे का उपयोग करता है (§8)।

3. आर्किटेक्चर अवलोकन

कोड-मोड स्क्रिप्ट (QuickJS VM, gateway)          Codex V8 स्क्रिप्ट (codex प्रक्रिया)  agents.run(...) ── पार्क की गई ब्रिज कॉल          tools.sessions_spawn / tools.agents_wait        │                                                │ आइटम/टूल/कॉल RPC (प्रत्येक ≤600s)        ▼                                                ▼             कोर (हार्नेस-अज्ञेय, यह रिपॉज़िटरी)  sessions_spawn {collect:true, outputSchema, fastMode, groupId}  agents_wait {ids, timeoutSeconds}        │  सबएजेंट रजिस्ट्री (SQLite): कलेक्टर पूर्णता रिकॉर्ड, swarm समूह आईडी        │  चाइल्ड = सामान्य सबएजेंट सत्र (लेन-सीमित, स्वीकृतियाँ विफलता पर बंद)        │  sessions.changed SSE ──► Control UI बिंदु / साइडबार / चैनल स्थिति संदेश

स्पॉन/पूर्णता/निपटान अर्थविज्ञान का एक प्रामाणिक स्वामी (कोर टूल + रजिस्ट्री)। प्रतीक्षा के दो परिवहन: QuickJS किसी ब्रिज कॉल को अनिश्चितकाल तक पार्क करता है (स्नैपशॉट); Codex सीमित RPC में agents_wait को पोल करता है।

4. कॉन्फ़िगरेशन गेट (v1)

नया tools.swarm (वैश्विक + प्रति-एजेंट ओवरराइड, वही मर्ज पैटर्न जो tools.codeMode का है):

"tools": {  "swarm": {    "enabled": false,            // मुख्य गेट, डिफ़ॉल्ट रूप से बंद    "maxConcurrent": 8,          // एक समय में चलने वाले चाइल्ड (swarm लेन सीमा)    "maxChildrenPerGroup": 50,   // प्रति swarm समूह सक्रिय चाइल्ड    "maxTotalPerGroup": 200,     // प्रति समूह आजीवन स्पॉन संख्या (अनियंत्रित वृद्धि की अंतिम रोक)    "waitTimeoutSecondsMax": 600,    "defaultAgentId": ""         // वैकल्पिक; जब स्पॉन में agentId न हो तब चाइल्ड एजेंट आईडी  }}

• Zod: CodeModeSchema जैसा यूनियन boolean | strict object (src/config/zod-schema.agent-runtime.ts); swarm: true → {enabled: true}।
• src/config/types.tools.ts में प्रकार (प्रति-एजेंट और शीर्ष-स्तरीय tools दोनों), schema.labels.ts में लेबल, schema.help.runtime.ts में सहायता।
• रिज़ॉल्यूशन सहायक resolveSwarmConfig(cfg, agentId), जो resolveCodeModeConfig (src/agents/code-mode.ts:215) के अनुरूप है और सभी संख्याओं को सीमित करता है।
• अक्षम होने पर गेट के प्रभाव: कैटलॉग में agents_wait टूल अनुपस्थित; sessions_spawn पर collect/outputSchema/fastMode/groupId पैरामीटर कॉन्फ़िगरेशन कुंजी का नाम बताने वाली स्पष्ट त्रुटि के साथ अस्वीकार किए जाते हैं। अन्य व्यवहार में कोई बदलाव नहीं।
• defaultAgentId को resolveSubagentAllowedTargetIds (src/agents/subagent-target-policy.ts) के माध्यम से सत्यापित किया जाता है; अज्ञात आईडी → स्पॉन त्रुटि, फ़ॉलबैक नहीं।

5. कोर: कलेक्टर-मोड स्पॉन + agents_wait (v1)

5.1 sessions_spawn में परिवर्धन (सभी swarm सक्षम होने पर निर्भर)

• collect: boolean — true होने पर चाइल्ड रन को expectsCompletionMessage: false और घोषणा/स्टीयरिंग डिलीवरी के बजाय एक कलेक्टर पूर्णता रिकॉर्ड के साथ पंजीकृत किया जाता है। टूल तुरंत { runId, sessionKey } लौटाता है। कोई चैनल/थ्रेड बाइंडिंग नहीं।
• outputSchema: object — JSON Schema। चाइल्ड की टूल सतह में एक कृत्रिम structured_output टूल जोड़ा जाता है; सिस्टम-प्रॉम्प्ट परिशिष्ट उसे अपने अंतिम परिणाम के साथ इसे ठीक एक बार कॉल करने का निर्देश देता है। सत्यापन विफल होने पर चाइल्ड को पुनः प्रयास के लिए एक संकेत मिलता है; उसके बाद पूर्णता रिकॉर्ड में structured: undefined, कच्चा टेक्स्ट और एक schemaError होता है।
• fastMode: true | "auto" | false — resolveSubagentModelAndThinkingPlan (src/agents/subagent-spawn-plan.ts) के माध्यम से मॉडल/थिंकिंग के साथ चाइल्ड सत्र पैच में पहुँचाया जाता है, मौजूदा FastMode अक्ष (src/shared/fast-mode.ts) का उपयोग करते हुए। छोड़ा गया = इनहेरिट।
• groupId: string — swarm समूह की मुहर। डिफ़ॉल्ट swarm:<requesterSessionKey>:<runId-of-requesting-run> है। रजिस्ट्री रिकॉर्ड और चाइल्ड सत्र पंक्ति में स्थायी रूप से रखा जाता है। सीमाओं, सूचीकरण, बैच संग्रह और बिंदुओं के लिए उपयोग होता है।
• label: string पहले से मौजूद है — बिंदुओं और subagents list में दिखाई देता है।
• चाइल्ड एजेंट आईडी: params.agentId → अन्यथा tools.swarm.defaultAgentId → अन्यथा अनुरोधकर्ता एजेंट (मौजूदा व्यवहार)।

5.2 स्वीकृतियाँ विफलता पर बंद

कलेक्टर चाइल्ड गैर-संवादात्मक स्वीकृति संदर्भ के साथ चलते हैं: ऑपरेटर स्वीकृति की आवश्यकता वाली कोई भी टूल कॉल संरचित अस्वीकृति (approval_required) के रूप में हल होती है, जो चाइल्ड को दिखाई देती है और चाइल्ड से अपने परिणाम में अवरोध रिपोर्ट करने की अपेक्षा की जाती है। कार्यान्वयन: कलेक्टर-मोड चाइल्ड रन के लिए बलपूर्वक deny रिज़ॉल्वर के साथ मौजूदा exec/टूल स्वीकृति नीति प्लंबिंग का पुनः उपयोग करें। कलेक्टर चाइल्ड से ऑपरेटर सतहों पर कोई स्वीकृति इवेंट उत्सर्जित नहीं होता।

5.3 agents_wait टूल (नया, गेटेड)

agents_wait({ ids: string[], timeoutSeconds?: number })→ {    पूर्ण: [{ runId, स्थिति: "पूर्ण"|"विफल"|"समाप्त"|"समय-समाप्त",                  परिणाम: string, संरचित?: unknown, स्कीमा-त्रुटि?: string,                  sessionKey, लेबल?, उपयोग?: {इनपुट-टोकन, आउटपुट-टोकन} }],    लंबित: string[]  }

• जैसे ही कम-से-कम एक आईडी पूर्ण होती है, यह लौटता है (प्रथम-पूर्णता / रेस अर्थविज्ञान, पाइपलाइन सक्षम करता है), या समय-समाप्ति पर completed: [] के साथ।
• timeoutSeconds का डिफ़ॉल्ट 30 है, जिसे waitTimeoutSecondsMax तक सीमित किया जाता है।
• आइडेम्पोटेंट: पहले से पूर्ण आईडी अपने रिकॉर्ड फिर लौटाती हैं (रिकॉर्ड समूह संग्रह तक रखे जाते हैं)। अज्ञात आईडी → प्रति-आईडी त्रुटि प्रविष्टि, थ्रो नहीं।
• स्वामित्व: केवल वह सत्र जिसने रन स्पॉन किया था (या उसकी पैरेंट शृंखला) उस पर प्रतीक्षा कर सकता है — कोड मोड में wait जैसा ही स्वामित्व नियम (code-mode.ts:1684)।
• रजिस्ट्री: पूर्णता रिकॉर्ड मौजूदा सबएजेंट रजिस्ट्री SQLite स्टोर (subagent-registry.store.sqlite.ts) में रहते हैं — नए फ़ील्ड, कोई नया स्टोर नहीं, कोई स्कीमा-संस्करण वृद्धि नहीं (केवल योगात्मक कॉलम; §9 की बाधा देखें)।

5.4 सीमाओं का प्रवर्तन

• maxConcurrent: कलेक्टर चाइल्ड मौजूदा सबएजेंट लेन पर चलते हैं, लेकिन प्रति swarm समूह गिने जाते हैं; सीमा से आगे के स्पॉन FIFO कतार में लगते हैं (होस्ट-पक्ष पर, स्पॉन पथ में — runId तुरंत लौटता है, स्लॉट खाली होने पर रन शुरू होता है)।
• maxChildrenPerGroup / maxTotalPerGroup: सीमा पार होते ही स्पॉन टाइप की गई त्रुटि के साथ अस्वीकार होता है; त्रुटि टेक्स्ट कॉन्फ़िगरेशन कुंजी का नाम बताता है।
• गहराई: कलेक्टर चाइल्ड DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH अर्थविज्ञान बनाए रखते हैं (चाइल्ड लीफ़ होते हैं, जब तक नेस्टिंग स्पष्ट रूप से कॉन्फ़िगर न की गई हो)।

6. परीक्षण अनुबंध (v1, लेन A)

• यूनिट: कॉन्फ़िगरेशन रिज़ॉल्यूशन/क्लैम्पिंग; अक्षम होने पर गेट अस्वीकृतियाँ; groupId डिफ़ॉल्टिंग; सीमा प्रवर्तन (कतार + अस्वीकृति); प्रतीक्षा रेस अर्थविज्ञान; प्रतीक्षा आइडेम्पोटेंसी; स्वामित्व अस्वीकृति; संरचित-आउटपुट सत्यापन + संकेत पुनः प्रयास + schemaError पथ; सत्र पैच में fastMode प्लंबिंग; defaultAgentId सत्यापन।
• एकीकरण (vitest, नकली मॉडल रनटाइम): 3 कलेक्टर चाइल्ड स्पॉन करें, लूप में प्रतीक्षा करें, प्रथम-पूर्णता क्रम और अंतिम निकासी सुनिश्चित करें; Gateway-रीस्टार्ट सिमुलेशन: रजिस्ट्री पुनः लोड → प्रतीक्षा स्थायी पूर्णता से हल होती है।
• सभी परीक्षण *.test.ts में साथ रखे गए हैं; कोई लाइव मॉडल कॉल नहीं।

7. QuickJS गेस्ट सतह (लेन B, कोर के बाद)

• गेस्ट ग्लोबल CONTROLLER_SOURCE (src/agents/code-mode.worker.ts:190-374) में स्थापित किए गए हैं, आरक्षित नाम code-mode-namespaces.ts में जोड़े गए हैं:
  • agents.run(prompt, opts) → Promise<result|structured> — सुविधाजनक रूप: कलेक्टर स्पॉन + समर्पित ब्रिज विधि (agentWait) पर पार्क की गई प्रतीक्षा, जिसे होस्ट पूर्णता पर हल करता है (कोई पोलिंग नहीं; स्नैपशॉट-सुरक्षित)।
  • agents.session(system, opts) → Promise<handle>; handle.send(input, opts) → Promise<...>; handle.close()। (v1.1 — run() के बाद जारी; mode:"session" + प्रति-टर्न कलेक्टर रिकॉर्ड का उपयोग करता है।)
  • phase(title), log(message) — बिना प्रतीक्षा वाली ब्रिज सूचनाएँ → swarm प्रगति इवेंट।
• ब्रिज विधियाँ CodeModeBridgeMethod (code-mode.ts:91) में जोड़ी गईं: agentSpawn, agentWait, swarmNote। agentSpawn/agentWait संरचना के कारण रीप्ले-सुरक्षित हैं: आइडेम्पोटेंसी कुंजी (codeModeRunId, bridgeId) रजिस्ट्री रिकॉर्ड में संग्रहीत होती है; रीस्टार्ट स्थायी पूर्णताओं से पुनः निपटान करता है और कभी दोबारा स्पॉन नहीं करता।
• लंबित agentWait ब्रिज कॉल रन की स्नैपशॉट TTL बढ़ाती हैं (लंबित एजेंट सेट ही संकेत है; कोई फ़्लैग नहीं)।
• API.read("agents.d.ts") वर्चुअल फ़ाइल टाइप की गई सतह और फ़ैन-आउट / गेट / चक्र मुहावरों (createCodeModeApiVirtualFiles, code-mode-namespaces.ts:876) का दस्तावेज़ीकरण करती है।

8. Codex हार्नेस प्रक्षेपण (बाद की लेन)

• sessions_spawn (नए पैरामीटर के साथ) और agents_wait मौजूदा डायनेमिक-टूल ब्रिज से प्रवाहित होते हैं; Codex कोड-मोड स्क्रिप्ट के अंदर वे अपने-आप tools.* के रूप में दिखाई देते हैं (सत्यापित: codex-rs/code-mode/src/runtime/globals.rs:14-65, codex-rs/core/src/tools/spec_plan.rs:448-507)।
• agents_wait को लंबी डायनेमिक-टूल समय-समाप्ति श्रेणी मिलती है (600s सीमा; extensions/codex/src/app-server/dynamic-tool-execution.ts:37-39) और इसे समय-समाप्ति/रीप्ले-सुरक्षित चिह्नित किया जाता है।
• Codex पैरेंट के लिए समूह कुंजी: swarm:<parentSessionKey>:<turnId>।
• Codex-मूल spawn_agent सबएजेंट साथ मौजूद रहते हैं; उनकी कार्य-मिरर पंक्तियाँ उसी प्रगति सतह को डेटा देती हैं।

9. स्थायित्व और अवधारण

• कोई नया स्टोर नहीं। रजिस्ट्री रिकॉर्ड मौजूदा सबएजेंट रजिस्ट्री SQLite तालिकाओं का विस्तार करते हैं; चाइल्ड सामान्य sessions पंक्तियाँ हैं। केवल योगात्मक कॉलम — SQLite स्कीमा-संस्करण बढ़ाने वाले किसी भी बदलाव के लिए पहले स्पष्ट मेंटेनर स्वीकृति आवश्यक है (रिपॉज़िटरी नीति)।
• रजिस्ट्री रिकॉर्ड + चाइल्ड सत्र मेटाडेटा पर swarm समूह आईडी।
• अवधारण: पूर्ण कलेक्टर रिकॉर्ड समूह संग्रह तक बने रहते हैं: जब पैरेंट रन समाप्त होता है (या TTL समाप्त होता है), समूह के चाइल्ड बैच के रूप में संग्रहित होते हैं (मौजूदा DEFAULT_SUBAGENT_ARCHIVE_AFTER_MINUTES स्वीप को प्रति समूह संचालित करने के लिए विस्तारित करें)।

10. प्रगति सतह ("बिंदु") — बाद की लेन

• अंतर्निहित, हार्नेस-संचालित। मौजूदा sessions.changed SSE + रजिस्ट्री से व्युत्पन्न; phase/log टिप्पणियाँ अर्थविज्ञान जोड़ती हैं। कोई एजेंट-संचालित रेंडरिंग नहीं।
• Control UI: वर्कस्पेस विजेट परिवार (ui/src/lib/workspace/widgets/) में swarm रेंडरर — चरण के अनुसार समूहित बिंदु ग्रिड, वर्णनकर्ता पंक्ति, प्रति-बिंदु स्थिति/लेबल/मॉडल; साइडबार चाइल्ड-ट्री अपरिवर्तित।
• चैनल: प्रति समूह एक सीमित-दर वाला संपादित स्थिति संदेश ( docs/concepts/streaming.md का अनुसरण करें; कभी भी प्रति-चाइल्ड संदेश नहीं)।

11. Labs पृष्ठ (Control UI, स्वतंत्र लेन)

Settings → Labs: प्रयोगात्मक फ़ीचर टॉगल, पहली प्रविष्टियाँ Code Mode और Swarm। प्रत्येक पंक्ति: नाम, एक-पंक्ति विवरण, दस्तावेज़ लिंक, मौजूदा config.patch RPC के माध्यम से जुड़ा टॉगल (RFC 7396 merge-patch — tools.codeMode.enabled / tools.swarm.enabled सेट करें), साथ ही लागू होने पर "पुनः आरंभ आवश्यक" संकेत। खोजने योग्य, लेकिन पाठ प्रयोगात्मक स्थिति स्पष्ट करता है। i18n: सभी स्ट्रिंग सामान्य en.ts + सिंक पाइपलाइन के माध्यम से।

12. प्लेसमेंट (बाद में)

• placement स्पॉन पर विकल्प: "local" (डिफ़ॉल्ट) | मौजूदा वर्कर-एनवायरनमेंट डिस्पैच (sessions.dispatch) के माध्यम से "cloud:<profile>"; यदि साझा-बॉक्स SSH-सैंडबॉक्स चाइल्ड अपर्याप्त सिद्ध हों, तो बाद में पूल्ड प्लेसमेंट।
• ऑर्केस्ट्रेटर VM हमेशा Gateway पर रहता है; सेटल/डॉट्स/बजट प्लेसमेंट से अनभिज्ञ हैं।

13. गैर-लक्ष्य

• कोई ग्राफ़ DSL नहीं — नियंत्रण प्रवाह ही ग्राफ़ है (जानबूझकर, दस्तावेज़ीकृत)।
• Codex स्रोत में कोई बदलाव नहीं; Codex Code Mode के आंतरिक भागों का पुनः उपयोग नहीं।
• v1 में कोई सहेजे गए/नामित वर्कफ़्लो नहीं; कोई CLI प्रवेश बिंदु नहीं।
• प्रति-चाइल्ड ऑपरेटर अनुमोदन का ऊपर तक प्रसार नहीं।
• फैन-आउट पैमाने पर कोई 1:1 क्लाउड प्रोविज़निंग नहीं।
• स्थिर-अवस्था रनटाइम संगतता शिम नहीं; स्वॉर्म नई सतह है, गेटेड।

14. बिल्ड चरण / PR विभाजन

1. लेन A (कोर): §4 कॉन्फ़िगरेशन + §5 स्पॉन/प्रतीक्षा/सीमाएँ/अनुमोदन + §6 परीक्षण।
2. लेन C (Labs पृष्ठ): §11 — स्वतंत्र, पहले लैंड हो सकती है।
3. लेन B (QuickJS सतह): §7 — A के अनुबंध लैंड होने के बाद।
4. डॉट्स रेंडरर (§10), Codex प्रोजेक्शन (§8), agents.session (§7 v1.1), प्लेसमेंट (§12), उपयोगकर्ता दस्तावेज़ों का पुनर्लेखन — इसी क्रम में अनुवर्ती PR।

प्रत्येक PR: हरी CI, $autoreview स्वच्छ, डिफ़ॉल्ट रूप से गेटेड ऑफ़, मुख्य शाखा शिप करने योग्य।