एक्सटेंशन लोडिंग (TypeScript/JavaScript मॉड्यूल)

यह दस्तावेज़ इस बात को कवर करता है कि कोडिंग एजेंट स्टार्टअप पर एक्सटेंशन मॉड्यूल (.ts/.js) को कैसे खोजता और लोड करता है।

यह gemini-extension.json मैनिफ़ेस्ट एक्सटेंशन को कवर नहीं करता (जो अलग से प्रलेखित हैं)।

यह सबसिस्टम क्या करता है

एक्सटेंशन लोडिंग मॉड्यूल एंट्री फ़ाइलों की एक सूची बनाता है, Bun के साथ प्रत्येक मॉड्यूल को इम्पोर्ट करता है, उसकी फ़ैक्ट्री को निष्पादित करता है, और लौटाता है:

• लोड किए गए एक्सटेंशन परिभाषाएँ
• प्रति-पथ लोड त्रुटियाँ (पूरे लोड को रोके बिना)
• एक साझा एक्सटेंशन रनटाइम ऑब्जेक्ट जो बाद में ExtensionRunner द्वारा उपयोग किया जाता है

प्राथमिक कार्यान्वयन फ़ाइलें

• src/extensibility/extensions/loader.ts — पथ खोज + इम्पोर्ट/निष्पादन
• src/extensibility/extensions/index.ts — सार्वजनिक एक्सपोर्ट
• src/extensibility/extensions/runner.ts — लोड के बाद रनटाइम/इवेंट निष्पादन
• src/discovery/builtin.ts — एक्सटेंशन मॉड्यूल के लिए नेटिव ऑटो-डिस्कवरी प्रोवाइडर
• src/config/settings.ts — मर्ज किए गए extensions / disabledExtensions सेटिंग्स लोड करता है

---

एक्सटेंशन लोडिंग के इनपुट

1) ऑटो-डिस्कवर किए गए नेटिव एक्सटेंशन मॉड्यूल

discoverAndLoadExtensions() पहले डिस्कवरी प्रोवाइडर्स से extension-module कैपेबिलिटी आइटम माँगता है, फिर केवल प्रोवाइडर native आइटम रखता है।

प्रभावी नेटिव स्थान:

• प्रोजेक्ट: <cwd>/.xcsh/extensions
• उपयोगकर्ता: ~/.xcsh/agent/extensions

पथ रूट नेटिव प्रोवाइडर (SOURCE_PATHS.native) से आते हैं।

नोट्स:

• नेटिव ऑटो-डिस्कवरी वर्तमान में .xcsh आधारित है।
• लेगेसी .pi अभी भी package.json मैनिफ़ेस्ट कीज़ (pi.extensions) में स्वीकृत है, लेकिन यहाँ नेटिव रूट के रूप में नहीं।

2) स्पष्ट रूप से कॉन्फ़िगर किए गए पथ

ऑटो-डिस्कवरी के बाद, कॉन्फ़िगर किए गए पथ जोड़े और रिज़ॉल्व किए जाते हैं।

मुख्य सेशन स्टार्टअप पथ (sdk.ts) में कॉन्फ़िगर किए गए पथ स्रोत:

1. CLI-प्रदत्त पथ (--extension/-e, और --hook को भी एक्सटेंशन पथ के रूप में माना जाता है)
2. सेटिंग्स extensions ऐरे (मर्ज किए गए ग्लोबल + प्रोजेक्ट सेटिंग्स)

ग्लोबल सेटिंग्स फ़ाइल:

• ~/.xcsh/agent/config.yml (या PI_CODING_AGENT_DIR के माध्यम से कस्टम एजेंट डायरेक्टरी)

प्रोजेक्ट सेटिंग्स फ़ाइल:

• <cwd>/.xcsh/settings.json

उदाहरण:

~/.xcsh/agent/config.yml

extensions:
  - ~/my-exts/safety.ts
  - ./local/ext-pack

{
  "extensions": ["./.xcsh/extensions/my-extra"]
}

---

सक्षम/अक्षम नियंत्रण

डिस्कवरी अक्षम करना

• CLI: --no-extensions
• SDK विकल्प: disableExtensionDiscovery

व्यवहार विभाजन:

• SDK: जब disableExtensionDiscovery=true हो, तब भी यह loadExtensions() के माध्यम से additionalExtensionPaths लोड करता है।
• CLI पथ निर्माण (main.ts) वर्तमान में --no-extensions सेट होने पर CLI एक्सटेंशन पथ साफ़ कर देता है, इसलिए उस मोड में स्पष्ट -e/--hook अग्रेषित नहीं किए जाते।

विशिष्ट एक्सटेंशन मॉड्यूल अक्षम करना

disabledExtensions सेटिंग एक्सटेंशन id प्रारूप द्वारा फ़िल्टर करती है:

• extension-module:<derivedName>

derivedName एंट्री पथ (getExtensionNameFromPath) पर आधारित है, उदाहरण के लिए:

• /x/foo.ts -> foo
• /x/bar/index.ts -> bar

उदाहरण:

disabledExtensions:
  - extension-module:foo

---

पथ और एंट्री रिज़ॉल्यूशन

पथ सामान्यीकरण

कॉन्फ़िगर किए गए पथों के लिए:

1. यूनिकोड स्पेस सामान्यीकरण
2. ~ का विस्तार
3. यदि सापेक्ष है, तो वर्तमान cwd के विरुद्ध रिज़ॉल्व करें

यदि कॉन्फ़िगर किया गया पथ एक फ़ाइल है

इसे सीधे मॉड्यूल एंट्री उम्मीदवार के रूप में उपयोग किया जाता है।

यदि कॉन्फ़िगर किया गया पथ एक डायरेक्टरी है

रिज़ॉल्यूशन क्रम:

1. उस डायरेक्टरी में package.json जिसमें xcsh.extensions (या लेगेसी pi.extensions) हो -> घोषित एंट्रीज़ का उपयोग करें
2. index.ts
3. index.js
4. अन्यथा एक स्तर तक एक्सटेंशन एंट्रीज़ के लिए स्कैन करें:
   • सीधी *.ts / *.js
   • सबडायरेक्टरी index.ts / index.js
   • सबडायरेक्टरी package.json जिसमें xcsh.extensions / pi.extensions हो

नियम और प्रतिबंध:

• एक सबडायरेक्टरी स्तर से परे कोई पुनरावर्ती खोज नहीं
• घोषित extensions मैनिफ़ेस्ट एंट्रीज़ उस पैकेज डायरेक्टरी के सापेक्ष रिज़ॉल्व की जाती हैं
• घोषित एंट्रीज़ केवल तभी शामिल की जाती हैं जब फ़ाइल मौजूद हो/एक्सेस की अनुमति हो
• */index.{ts,js} जोड़ों में, TypeScript को JavaScript पर प्राथमिकता दी जाती है
• सिमलिंक को पात्र फ़ाइलों/डायरेक्टरियों के रूप में माना जाता है

इग्नोर व्यवहार स्रोत के अनुसार भिन्न होता है

• नेटिव ऑटो-डिस्कवरी (डिस्कवरी हेल्पर्स में discoverExtensionModulePaths) नेटिव glob का उपयोग करती है जिसमें gitignore: true और hidden: false हो।
• loader.ts में स्पष्ट कॉन्फ़िगर्ड डायरेक्टरी स्कैनिंग readdir नियमों का उपयोग करती है और gitignore फ़िल्टरिंग लागू नहीं करती।

---

लोड क्रम और प्राथमिकता

discoverAndLoadExtensions() एक क्रमबद्ध सूची बनाता है और फिर loadExtensions() को कॉल करता है।

क्रम:

1. नेटिव ऑटो-डिस्कवर किए गए मॉड्यूल
2. स्पष्ट कॉन्फ़िगर किए गए पथ (प्रदान किए गए क्रम में)

sdk.ts में, कॉन्फ़िगर्ड क्रम है:

1. CLI अतिरिक्त पथ
2. सेटिंग्स extensions

डी-डुप्लिकेशन:

• एब्सोल्यूट पथ आधारित
• पहले देखा गया पथ जीतता है
• बाद के डुप्लिकेट अनदेखे किए जाते हैं

निहितार्थ: यदि एक ही मॉड्यूल पथ ऑटो-डिस्कवर और स्पष्ट रूप से कॉन्फ़िगर दोनों है, तो यह पहली स्थिति (ऑटो-डिस्कवर चरण) पर एक बार लोड होता है।

---

मॉड्यूल इम्पोर्ट और फ़ैक्ट्री अनुबंध

प्रत्येक उम्मीदवार पथ को डायनेमिक इम्पोर्ट से लोड किया जाता है:

• await import(resolvedPath)
• फ़ैक्ट्री module.default ?? module है
• फ़ैक्ट्री एक फ़ंक्शन (ExtensionFactory) होनी चाहिए

यदि एक्सपोर्ट एक फ़ंक्शन नहीं है, तो वह पथ एक संरचित त्रुटि के साथ विफल होता है और लोडिंग जारी रहती है।

---

विफलता हैंडलिंग और आइसोलेशन

लोडिंग के दौरान

प्रति एक्सटेंशन पथ, विफलताओं को { path, error } के रूप में कैप्चर किया जाता है और अन्य पथों को लोड होने से नहीं रोकता।

सामान्य मामले:

• इम्पोर्ट विफलता / अनुपस्थित फ़ाइल
• अमान्य फ़ैक्ट्री एक्सपोर्ट (नॉन-फ़ंक्शन)
• फ़ैक्ट्री निष्पादित करते समय अपवाद फेंका गया

रनटाइम आइसोलेशन मॉडल

• एक्सटेंशन सैंडबॉक्स्ड नहीं हैं (समान प्रोसेस/रनटाइम)।
• वे एक EventBus और एक ExtensionRuntime इंस्टेंस साझा करते हैं।
• लोड के दौरान, रनटाइम एक्शन मेथड जानबूझकर ExtensionRuntimeNotInitializedError फेंकते हैं; एक्शन वायरिंग बाद में ExtensionRunner.initialize() में होती है।

लोडिंग के बाद

जब इवेंट ExtensionRunner के माध्यम से चलते हैं, तो हैंडलर अपवादों को पकड़ा जाता है और रनर लूप को क्रैश करने के बजाय एक्सटेंशन त्रुटियों के रूप में उत्सर्जित किया जाता है।

---

न्यूनतम उपयोगकर्ता/प्रोजेक्ट लेआउट उदाहरण

उपयोगकर्ता-स्तर

~/.xcsh/agent/
  config.yml
  extensions/
    guardrails.ts
    audit/
      index.ts

प्रोजेक्ट-स्तर

<repo>/
  .xcsh/
    settings.json
    extensions/
      checks/
        package.json
      lint-gates.ts

checks/package.json:

{
  "xcsh": {
    "extensions": ["./src/check-a.ts", "./src/check-b.js"]
  }
}

लेगेसी मैनिफ़ेस्ट कुंजी अभी भी स्वीकृत:

{
  "pi": {
    "extensions": ["./index.ts"]
  }
}