टास्क एजेंट डिस्कवरी और सिलेक्शन

यह दस्तावेज़ बताता है कि टास्क सबसिस्टम कैसे एजेंट डेफिनिशन्स की खोज करता है, कई स्रोतों को मर्ज करता है, और एक्सीक्यूशन समय पर अनुरोधित एजेंट को रिज़ॉल्व करता है।

यह आज के कार्यान्वित रनटाइम व्यवहार को कवर करता है, जिसमें प्रेसीडेंस, अमान्य-डेफिनिशन हैंडलिंग, और spawn/depth बाधाएँ शामिल हैं जो किसी एजेंट को प्रभावी रूप से अनुपलब्ध बना सकती हैं।

इम्प्लीमेंटेशन फ़ाइलें

• src/task/discovery.ts
• src/task/agents.ts
• src/task/types.ts
• src/task/index.ts
• src/task/commands.ts
• src/prompts/agents/task.md
• src/prompts/tools/task.md
• src/discovery/helpers.ts
• src/config.ts
• src/task/executor.ts

---

एजेंट डेफिनिशन का आकार

टास्क एजेंट्स AgentDefinition (src/task/types.ts) में नॉर्मलाइज़ होते हैं:

• name, description, systemPrompt (एक वैध लोडेड एजेंट के लिए आवश्यक)
• वैकल्पिक tools, spawns, model, thinkingLevel, output
• source: "bundled" | "user" | "project"
• वैकल्पिक filePath

पार्सिंग parseAgentFields() (src/discovery/helpers.ts) के माध्यम से frontmatter से आती है:

• name या description गायब होने पर => अमान्य (null), कॉलर इसे पार्स विफलता मानता है
• tools CSV या array स्वीकार करता है; यदि प्रदान किया गया हो, तो submit_result स्वतः जोड़ा जाता है
• spawns *, CSV, या array स्वीकार करता है
• बैकवर्ड-कम्पैट व्यवहार: यदि spawns गायब है लेकिन tools में task शामिल है, तो spawns * बन जाता है
• output अपारदर्शी स्कीमा डेटा के रूप में पास किया जाता है

बंडल्ड एजेंट्स

बंडल्ड एजेंट्स बिल्ड समय पर (src/task/agents.ts) टेक्स्ट इम्पोर्ट्स का उपयोग करके एम्बेड किए जाते हैं।

EMBEDDED_AGENT_DEFS परिभाषित करता है:

• प्रॉम्प्ट फ़ाइलों से explore, plan, designer, reviewer
• साझा task.md बॉडी प्लस इंजेक्टेड frontmatter से task और quick_task

लोडिंग पथ:

1. loadBundledAgents() एम्बेडेड मार्कडाउन को parseAgent(..., "bundled", "fatal") से पार्स करता है
2. परिणाम इन-मेमोरी कैश किए जाते हैं (bundledAgentsCache)
3. clearBundledAgentsCache() केवल टेस्ट के लिए कैश रीसेट है

चूंकि बंडल्ड पार्सिंग level: "fatal" का उपयोग करती है, विकृत बंडल्ड frontmatter थ्रो करता है और पूरी डिस्कवरी विफल कर सकता है।

फ़ाइलसिस्टम और प्लगइन डिस्कवरी

discoverAgents(cwd, home) (src/task/discovery.ts) बंडल्ड डेफिनिशन्स जोड़ने से पहले कई स्थानों से एजेंट्स को मर्ज करता है।

डिस्कवरी इनपुट्स

1. getConfigDirs("agents", { project: false }) से उपयोगकर्ता कॉन्फ़िग एजेंट डायरेक्टरीज़
2. findAllNearestProjectConfigDirs("agents", cwd) से निकटतम प्रोजेक्ट एजेंट डायरेक्टरीज़
3. agents/ सबडायरेक्टरीज़ के साथ Claude प्लगइन रूट्स (listClaudePluginRoots(home))
4. बंडल्ड एजेंट्स (loadBundledAgents())

वास्तविक स्रोत क्रम

स्रोत-परिवार का क्रम getConfigDirs("", { project: false }) से आता है, जो src/config.ts में priorityList से प्राप्त होता है:

1. .xcsh
2. .claude
3. .codex
4. .gemini

प्रत्येक स्रोत परिवार के लिए, डिस्कवरी क्रम है:

1. उस स्रोत के लिए निकटतम प्रोजेक्ट डायरेक्टरी (यदि मिली)
2. उस स्रोत के लिए उपयोगकर्ता डायरेक्टरी

सभी स्रोत-परिवार डायरेक्टरीज़ के बाद, प्लगइन agents/ डायरेक्टरीज़ जोड़ी जाती हैं (पहले प्रोजेक्ट-स्कोप प्लगइन्स, फिर उपयोगकर्ता-स्कोप)।

बंडल्ड एजेंट्स सबसे अंत में जोड़े जाते हैं।

महत्वपूर्ण चेतावनी: पुरानी टिप्पणियाँ बनाम वर्तमान कोड

discovery.ts हेडर टिप्पणियाँ अभी भी .pi का उल्लेख करती हैं और .codex/.gemini का उल्लेख नहीं करतीं। वास्तविक रनटाइम क्रम src/config.ts द्वारा संचालित है और वर्तमान में .xcsh, .claude, .codex, .gemini का उपयोग करता है।

मर्ज और कोलिज़न नियम

डिस्कवरी सटीक agent.name द्वारा first-wins डीडुप का उपयोग करती है:

• एक Set<string> देखे गए नामों को ट्रैक करता है।
• लोड किए गए एजेंट्स डायरेक्टरी क्रम में फ़्लैटन किए जाते हैं और केवल तभी रखे जाते हैं जब नाम नहीं देखा गया हो।
• बंडल्ड एजेंट्स उसी सेट के विरुद्ध फ़िल्टर किए जाते हैं और केवल तभी जोड़े जाते हैं जब अभी भी नहीं देखे गए हों।

निहितार्थ:

• समान स्रोत परिवार के लिए प्रोजेक्ट उपयोगकर्ता को ओवरराइड करता है।
• उच्च-प्राथमिकता स्रोत परिवार निम्न को ओवरराइड करता है (.xcsh .claude से पहले, आदि)।
• गैर-बंडल्ड एजेंट्स समान नाम वाले बंडल्ड एजेंट्स को ओवरराइड करते हैं।
• नाम मिलान केस-सेंसिटिव है (Task और task अलग-अलग हैं)।
• एक डायरेक्टरी के भीतर, मार्कडाउन फ़ाइलें डीडुप से पहले लेक्सिकोग्राफ़िक फ़ाइलनाम क्रम में पढ़ी जाती हैं।

अमान्य/गायब एजेंट फ़ाइल व्यवहार

प्रति डायरेक्टरी (loadAgentsFromDir):

• अपठनीय/गायब डायरेक्टरी: खाली माना जाता है (readdir(...).catch(() => []))
• फ़ाइल पढ़ने या पार्स विफलता: चेतावनी लॉग की जाती है, फ़ाइल छोड़ दी जाती है
• पार्स पथ parseAgent(..., level: "warn") का उपयोग करता है

Frontmatter विफलता व्यवहार parseFrontmatter से आता है:

• warn स्तर पर पार्स त्रुटि चेतावनी लॉग करती है
• पार्सर एक सरल key: value लाइन पार्सर पर फ़ॉलबैक करता है
• यदि आवश्यक फ़ील्ड अभी भी गायब हैं, तो parseAgentFields विफल हो जाता है, फिर AgentParsingError थ्रो किया जाता है और कॉलर द्वारा पकड़ा जाता है (फ़ाइल छोड़ दी जाती है)

कुल प्रभाव: एक खराब कस्टम एजेंट फ़ाइल अन्य फ़ाइलों की डिस्कवरी को रोकती नहीं है।

एजेंट लुकअप और सिलेक्शन

लुकअप सटीक-नाम लीनियर सर्च है:

• getAgent(agents, name) => agents.find(a => a.name === name)

टास्क एक्सीक्यूशन में (TaskTool.execute):

1. कॉल समय पर एजेंट्स फिर से खोजे जाते हैं (discoverAgents(this.session.cwd))
2. अनुरोधित params.agent को getAgent के माध्यम से रिज़ॉल्व किया जाता है
3. गायब एजेंट तत्काल टूल प्रतिक्रिया लौटाता है:
   • Unknown agent "...". Available: ...
   • कोई सबप्रोसेस नहीं चलता

विवरण बनाम एक्सीक्यूशन-समय डिस्कवरी

TaskTool.create() इनिशियलाइज़ेशन समय पर डिस्कवरी परिणामों से टूल विवरण बनाता है (buildDescription)।

execute() फिर से एजेंट्स खोजता है। इसलिए रनटाइम सेट पहले के टूल विवरण में सूचीबद्ध से भिन्न हो सकता है यदि सत्र के बीच एजेंट फ़ाइलें बदल गई हों।

स्ट्रक्चर्ड-आउटपुट गार्डरेल्स और स्कीमा प्रेसीडेंस

TaskTool.execute में रनटाइम आउटपुट स्कीमा प्रेसीडेंस:

1. एजेंट frontmatter output
2. टास्क कॉल params.schema
3. पैरेंट सेशन outputSchema

(effectiveOutputSchema = effectiveAgent.output ?? outputSchema ?? this.session.outputSchema)

src/prompts/tools/task.md में प्रॉम्प्ट-समय गार्डरेल टेक्स्ट स्ट्रक्चर्ड-आउटपुट एजेंट्स (explore, reviewer) के लिए मिसमैच व्यवहार के बारे में चेतावनी देता है: प्रोज़ में आउटपुट-फ़ॉर्मेट निर्देश बिल्ट-इन स्कीमा के साथ विरोध कर सकते हैं और null आउटपुट उत्पन्न कर सकते हैं।

यह मार्गदर्शन है, discoverAgents में कठोर रनटाइम वैलिडेशन लॉजिक नहीं।

कमांड डिस्कवरी इंटरैक्शन

src/task/commands.ts वर्कफ़्लो कमांड्स (एजेंट डेफिनिशन्स नहीं) के लिए समानांतर इन्फ्रास्ट्रक्चर है, लेकिन यह समग्र रूप से समान पैटर्न का अनुसरण करता है:

• पहले कैपेबिलिटी प्रोवाइडर्स से खोजें
• first-wins के साथ नाम द्वारा डीडुप्लिकेट करें
• यदि अभी भी नहीं देखे गए हों तो बंडल्ड कमांड्स जोड़ें
• getCommand के माध्यम से सटीक-नाम लुकअप

src/task/index.ts में, कमांड हेल्पर्स एजेंट डिस्कवरी हेल्पर्स के साथ री-एक्सपोर्ट किए जाते हैं। एजेंट डिस्कवरी स्वयं रनटाइम पर कमांड डिस्कवरी पर निर्भर नहीं करती।

डिस्कवरी से परे उपलब्धता बाधाएँ

एक एजेंट खोजने योग्य हो सकता है लेकिन एक्सीक्यूशन गार्डरेल्स के कारण चलाने के लिए अभी भी अनुपलब्ध हो सकता है।

पैरेंट spawn पॉलिसी

TaskTool.execute session.getSessionSpawns() की जाँच करता है:

• "*" => किसी भी को अनुमति दें
• "" => सभी को अस्वीकार करें
• CSV सूची => केवल सूचीबद्ध नामों को अनुमति दें

यदि अस्वीकृत: तत्काल Cannot spawn '...'. Allowed: ... प्रतिक्रिया।

ब्लॉक्ड सेल्फ-रिकर्सन env गार्ड

PI_BLOCKED_AGENT टूल कंस्ट्रक्शन पर पढ़ा जाता है। यदि अनुरोध मेल खाता है, तो रिकर्सन-रोकथाम संदेश के साथ एक्सीक्यूशन अस्वीकार किया जाता है।

रिकर्सन-डेप्थ गेटिंग (चाइल्ड सेशन्स के अंदर टास्क टूल उपलब्धता)

runSubprocess (src/task/executor.ts) में:

• डेप्थ taskDepth से गणना की जाती है
• task.maxRecursionDepth कटऑफ़ नियंत्रित करता है
• अधिकतम डेप्थ पर:
  • task टूल चाइल्ड टूल सूची से हटा दिया जाता है
  • चाइल्ड spawns env खाली पर सेट किया जाता है

इसलिए गहरे स्तर आगे टास्क स्पॉन नहीं कर सकते, भले ही एजेंट डेफिनिशन में spawns शामिल हो।

प्लान मोड चेतावनी (वर्तमान इम्प्लीमेंटेशन)

TaskTool.execute प्लान मोड के लिए एक effectiveAgent की गणना करता है (प्लान-मोड प्रॉम्प्ट प्रीपेंड करता है, रीड-ओनली टूल सबसेट फ़ोर्स करता है, spawns क्लियर करता है), लेकिन runSubprocess को effectiveAgent के बजाय agent के साथ कॉल किया जाता है।

वर्तमान प्रभाव:

• मॉडल ओवरराइड / थिंकिंग लेवल / आउटपुट स्कीमा effectiveAgent से प्राप्त होते हैं
• effectiveAgent से सिस्टम प्रॉम्प्ट और टूल/spawn प्रतिबंध इस कॉल पथ में पास नहीं किए जाते

यह एक इम्प्लीमेंटेशन चेतावनी है जिसे प्लान-मोड व्यवहार अपेक्षाओं को पढ़ते समय जानना उपयोगी है।