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

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

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

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

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

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

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

• लागत: कॉन्फ़िगरेशन सीमाएँ लागू; प्रति-स्वॉर्म टोकन बजट वैकल्पिक। कोई अनिवार्य बजट नहीं।
• अनुमोदन: चाइल्ड फ़ेल-क्लोज़्ड / गैर-इंटरैक्टिव रूप से चलते हैं। अनुमोदन की आवश्यकता वाली कार्रवाइयाँ अस्वीकार की जाती हैं; अस्वीकृति चाइल्ड परिणाम में रिपोर्ट होती है; निर्णय स्क्रिप्ट करती है। फ़ैन-आउट से ऑपरेटर प्रॉम्प्ट की बाढ़ नहीं आती।
• 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): कलेक्टर पूर्णता रिकॉर्ड, स्वॉर्म समूह आईडी        │  चाइल्ड = सामान्य सबएजेंट सेशन (लेन-सीमित, फ़ेल-क्लोज़्ड अनुमोदन)        │  sessions.changed SSE ──► Control UI डॉट / साइडबार / चैनल स्थिति संदेश

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

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

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

"tools": {  "swarm": {    "enabled": false,            // मुख्य गेट, डिफ़ॉल्ट रूप से बंद    "maxConcurrent": 8,          // एक साथ चलने वाले चाइल्ड (स्वॉर्म लेन सीमा)    "maxChildrenPerGroup": 50,   // प्रति स्वॉर्म समूह सक्रिय चाइल्ड    "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 में परिवर्धन (सभी स्वॉर्म सक्षम होने पर गेटेड)

• collect: boolean — सही होने पर, चाइल्ड रन को अनाउंस/स्टीयरिंग डिलीवरी के बजाय expectsCompletionMessage: false और एक कलेक्टर पूर्णता रिकॉर्ड के साथ पंजीकृत किया जाता है। टूल तत्काल { runId, sessionKey } लौटाता है। कोई चैनल/थ्रेड बाइंडिंग नहीं।
• outputSchema: object — JSON Schema। चाइल्ड के टूल सरफ़ेस में एक कृत्रिम structured_output टूल जोड़ा जाता है; सिस्टम-प्रॉम्प्ट परिशिष्ट उसे अपने अंतिम परिणाम के साथ ठीक एक बार कॉल करने का निर्देश देता है। सत्यापन विफल होने पर चाइल्ड को दोबारा प्रयास करने के लिए एक संकेत मिलता है; उसके बाद पूर्णता रिकॉर्ड में structured: undefined, साथ में अपरिष्कृत टेक्स्ट और एक schemaError होता है।
• fastMode: true | "auto" | false — मौजूदा FastMode अक्ष (src/shared/fast-mode.ts) का उपयोग करके resolveSubagentModelAndThinkingPlan (src/agents/subagent-spawn-plan.ts) के माध्यम से मॉडल/थिंकिंग के साथ चाइल्ड सेशन पैच में प्रवाहित। छोड़ा गया = इनहेरिट।
• groupId: string — स्वॉर्म समूह स्टैम्प। डिफ़ॉल्ट 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 })→ {    completed: [{ runId, status: "done"|"failed"|"killed"|"timeout",                  result: string, structured?: unknown, schemaError?: string,                  sessionKey, label?, usage?: {inputTokens, outputTokens} }],    pending: string[]  }

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

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

• maxConcurrent: कलेक्टर चाइल्ड मौजूदा सबएजेंट लेन पर चलते हैं, लेकिन उनकी गणना प्रति स्वॉर्म समूह होती है; सीमा से आगे के स्पॉन 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) — फ़ायर-एंड-फ़ॉरगेट ब्रिज सूचनाएँ → स्वॉर्म प्रगति इवेंट।
• ब्रिज विधियाँ 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 स्कीमा-संस्करण बढ़ाने वाले किसी भी परिवर्तन के लिए पहले स्पष्ट मेंटेनर स्वीकृति आवश्यक है (रिपॉज़िटरी नीति)।
• रजिस्ट्री रिकॉर्ड + चाइल्ड सेशन मेटाडेटा पर स्वॉर्म समूह आईडी।
• प्रतिधारण: पूर्ण कलेक्टर रिकॉर्ड समूह आर्काइव तक बने रहते हैं: पैरेंट रन पूर्ण होने पर (या 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 मर्ज-पैच — tools.codeMode.enabled / tools.swarm.enabled सेट करें), साथ ही लागू होने पर "पुनः आरंभ आवश्यक" संकेत। खोजने योग्य, लेकिन पाठ प्रयोगात्मक स्थिति को स्पष्ट करता है। i18n: सभी स्ट्रिंग सामान्य en.ts + सिंक पाइपलाइन के माध्यम से।

12. स्थान-निर्धारण (बाद में)

• placement स्पॉन पर विकल्प: "local" (डिफ़ॉल्ट) | "cloud:<profile>" मौजूदा वर्कर-परिवेश डिस्पैच (sessions.dispatch) के माध्यम से; यदि साझा-बॉक्स 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 साफ़, डिफ़ॉल्ट रूप से गेटेड बंद, main शिप करने योग्य।