Bash टूल रनटाइम

यह दस्तावेज़ एजेंट टूल कॉल द्वारा उपयोग किए जाने वाले bash टूल रनटाइम पाथ का वर्णन करता है — कमांड नॉर्मलाइज़ेशन से लेकर निष्पादन, ट्रंकेशन/आर्टिफैक्ट और रेंडरिंग तक।

यह यह भी बताता है कि इंटरेक्टिव TUI, प्रिंट मोड, RPC मोड और यूज़र-इनिशिएटेड बैंग (!) शेल निष्पादन में व्यवहार कहाँ भिन्न होता है।

स्कोप और रनटाइम सर्फेस

coding-agent में दो अलग-अलग bash निष्पादन सर्फेस हैं:

1. टूल-कॉल सर्फेस (toolName: "bash"): जब मॉडल bash टूल को कॉल करता है तब उपयोग किया जाता है।
   • एंट्री पॉइंट: BashTool.execute()।
2. यूज़र बैंग-कमांड सर्फेस (इंटरेक्टिव इनपुट या RPC bash कमांड से !cmd): सेशन-लेवल हेल्पर पाथ।
   • एंट्री पॉइंट: AgentSession.executeBash()।

दोनों अंततः नॉन-PTY निष्पादन के लिए src/exec/bash-executor.ts में executeBash() का उपयोग करते हैं, लेकिन केवल टूल-कॉल पाथ नॉर्मलाइज़ेशन/इंटरसेप्शन और टूल रेंडरर लॉजिक चलाता है।

एंड-टू-एंड टूल-कॉल पाइपलाइन

1) इनपुट नॉर्मलाइज़ेशन और पैरामीटर मर्ज

BashTool.execute() पहले normalizeBashCommand() के माध्यम से रॉ कमांड को नॉर्मलाइज़ करता है:

• अनुगामी | head -n N, | head -N, | tail -n N, | tail -N को स्ट्रक्चर्ड लिमिट में निकालता है,
• अनुगामी/अग्रणी व्हाइटस्पेस को ट्रिम करता है,
• आंतरिक व्हाइटस्पेस को बरकरार रखता है।

फिर यह निकाली गई लिमिट को स्पष्ट टूल आर्ग्स के साथ मर्ज करता है:

• स्पष्ट head/tail आर्ग्स निकाले गए मानों को ओवरराइड करते हैं,
• निकाले गए मान केवल फ़ॉलबैक हैं।

चेतावनी

bash-normalize.ts टिप्पणियों में 2>&1 हटाने का उल्लेख है, लेकिन वर्तमान कार्यान्वयन इसे नहीं हटाता। रनटाइम व्यवहार अभी भी सही है (stdout/stderr पहले से मर्ज हैं), लेकिन नॉर्मलाइज़ेशन व्यवहार टिप्पणियों की तुलना में संकीर्ण है।

2) वैकल्पिक इंटरसेप्शन (ब्लॉक्ड-कमांड पाथ)

यदि bashInterceptor.enabled true है, तो BashTool सेटिंग्स से नियम लोड करता है और नॉर्मलाइज़ किए गए कमांड के विरुद्ध checkBashInterception() चलाता है।

इंटरसेप्शन व्यवहार:

• कमांड केवल तभी ब्लॉक होती है जब:
  • regex नियम मेल खाता है, और
  • सुझाया गया टूल ctx.toolNames में मौजूद है।
• अमान्य regex नियम चुपचाप छोड़ दिए जाते हैं।
• ब्लॉक होने पर, BashTool संदेश के साथ ToolError थ्रो करता है:
  • Blocked: ...
  • मूल कमांड शामिल।

डिफ़ॉल्ट नियम पैटर्न (कोड में परिभाषित) सामान्य दुरुपयोगों को लक्षित करते हैं:

• फ़ाइल रीडर (cat, head, tail, …)
• सर्च उपकरण (grep, rg, …)
• फ़ाइल फाइंडर (find, fd, …)
• इन-प्लेस एडिटर (sed -i, perl -i, awk -i inplace)
• शेल रीडायरेक्शन राइट्स (echo ... > file, heredoc रीडायरेक्शन)

चेतावनी

InterceptionResult में suggestedTool शामिल है, लेकिन BashTool वर्तमान में केवल संदेश टेक्स्ट दिखाता है (details में कोई स्ट्रक्चर्ड suggested-tool फ़ील्ड नहीं)।

3) CWD वैलिडेशन और टाइमआउट क्लैंपिंग

cwd को सेशन cwd (resolveToCwd) के सापेक्ष रिज़ॉल्व किया जाता है, फिर stat के माध्यम से वैलिडेट किया जाता है:

• गायब पाथ -> ToolError("Working directory does not exist: ...")
• गैर-डायरेक्टरी -> ToolError("Working directory is not a directory: ...")

टाइमआउट को [1, 3600] सेकंड तक क्लैंप किया जाता है और मिलीसेकंड में कनवर्ट किया जाता है।

4) आर्टिफैक्ट आवंटन

निष्पादन से पहले, टूल ट्रंकेटेड आउटपुट स्टोरेज के लिए एक आर्टिफैक्ट पाथ/आईडी (बेस्ट-एफर्ट) आवंटित करता है।

• आर्टिफैक्ट आवंटन विफलता नॉन-फेटल है (निष्पादन आर्टिफैक्ट स्पिल फ़ाइल के बिना जारी रहता है),
• ट्रंकेशन पर पूर्ण-आउटपुट परसिस्टेंस के लिए आर्टिफैक्ट id/path निष्पादन पाथ में पास किए जाते हैं।

5) PTY बनाम नॉन-PTY निष्पादन चयन

BashTool PTY निष्पादन तभी चुनता है जब सभी शर्तें सत्य हों:

• bash.virtualTerminal === "on"
• PI_NO_PTY !== "1"
• टूल संदर्भ में UI है (ctx.hasUI === true और ctx.ui सेट)

अन्यथा यह नॉन-इंटरेक्टिव executeBash() का उपयोग करता है।

इसका मतलब है कि प्रिंट मोड और नॉन-UI RPC/टूल संदर्भ हमेशा नॉन-PTY का उपयोग करते हैं।

नॉन-इंटरेक्टिव निष्पादन इंजन (executeBash)

शेल सेशन पुनः उपयोग मॉडल

executeBash() एक प्रोसेस-ग्लोबल मैप में नेटिव Shell इंस्टेंस को कैश करता है जो निम्न द्वारा की-ड होता है:

• शेल पाथ,
• कॉन्फ़िगर किया गया कमांड प्रीफ़िक्स,
• स्नैपशॉट पाथ,
• सीरियलाइज़ किया गया शेल env,
• वैकल्पिक एजेंट सेशन की।

सेशन-लेवल निष्पादनों के लिए, AgentSession.executeBash() sessionKey: this.sessionId पास करता है, जो प्रति सेशन पुनः उपयोग को अलग करता है।

टूल-कॉल पाथ sessionKey पास नहीं करता, इसलिए पुनः उपयोग स्कोप शेल config/snapshot/env पर आधारित है।

शेल कॉन्फिग और स्नैपशॉट व्यवहार

प्रत्येक कॉल पर, executor सेटिंग्स शेल config (shell, env, वैकल्पिक prefix) लोड करता है।

यदि चुने गए शेल में bash शामिल है, तो यह getOrCreateSnapshot() का प्रयास करता है:

• स्नैपशॉट यूज़र rc से aliases/functions/options कैप्चर करता है,
• स्नैपशॉट निर्माण बेस्ट-एफर्ट है,
• विफलता नो-स्नैपशॉट पर फ़ॉलबैक करती है।

यदि prefix कॉन्फ़िगर किया गया है, तो कमांड बन जाता है:

<prefix> <command>

स्ट्रीमिंग और कैंसलेशन

Shell.run() कॉलबैक पर चंक स्ट्रीम करता है। Executor प्रत्येक चंक को OutputSink और वैकल्पिक onChunk कॉलबैक में पाइप करता है।

कैंसलेशन:

• अबॉर्टेड सिग्नल shellSession.abort(...) ट्रिगर करता है,
• नेटिव रिज़ल्ट से टाइमआउट को cancelled: true + एनोटेशन टेक्स्ट में मैप किया जाता है,
• स्पष्ट कैंसलेशन भी cancelled: true + एनोटेशन रिटर्न करता है।

टाइमआउट/कैंसल के लिए executor के अंदर कोई एक्सेप्शन नहीं थ्रो किया जाता; यह स्ट्रक्चर्ड BashResult रिटर्न करता है और कॉलर को एरर सेमेंटिक्स मैप करने देता है।

इंटरेक्टिव PTY पाथ (runInteractiveBashPty)

जब PTY सक्षम होता है, टूल runInteractiveBashPty() चलाता है जो एक ओवरले कंसोल घटक खोलता है और एक नेटिव PtySession चलाता है।

व्यवहार की मुख्य विशेषताएं:

• xterm-headless वर्चुअल टर्मिनल ओवरले में व्यूपोर्ट रेंडर करता है,
• कीबोर्ड इनपुट नॉर्मलाइज़ किया जाता है (Kitty सीक्वेंस और एप्लिकेशन कर्सर मोड हैंडलिंग सहित),
• चलते समय esc PTY सेशन को किल करता है,
• टर्मिनल रीसाइज़ PTY में प्रोपेगेट होता है (session.resize(cols, rows))।

अनअटेंडेड रन के लिए एनवायरनमेंट हार्डनिंग डिफ़ॉल्ट इंजेक्ट किए जाते हैं:

• पेजर अक्षम (PAGER=cat, GIT_PAGER=cat, आदि),
• एडिटर प्रॉम्प्ट अक्षम (GIT_EDITOR=true, EDITOR=true, …),
• टर्मिनल/ऑथ प्रॉम्प्ट कम (GIT_TERMINAL_PROMPT=0, SSH_ASKPASS=/usr/bin/false, CI=1),
• नॉन-इंटरेक्टिव व्यवहार के लिए पैकेज-मैनेजर/टूल ऑटोमेशन फ्लैग।

PTY आउटपुट नॉर्मलाइज़ किया जाता है (CRLF/CR से LF, sanitizeText) और OutputSink में लिखा जाता है, जिसमें आर्टिफैक्ट स्पिल सपोर्ट शामिल है।

PTY स्टार्टअप/रनटाइम एरर पर, sink को PTY error: ... लाइन मिलती है और कमांड undefined exit code के साथ समाप्त होता है।

आउटपुट हैंडलिंग: स्ट्रीमिंग, ट्रंकेशन, आर्टिफैक्ट स्पिल

PTY और नॉन-PTY दोनों पाथ OutputSink का उपयोग करते हैं।

OutputSink सेमेंटिक्स

• इन-मेमोरी UTF-8-सेफ टेल बफ़र रखता है (DEFAULT_MAX_BYTES, वर्तमान में 50KB),
• देखे गए कुल बाइट्स/लाइनें ट्रैक करता है,
• यदि आर्टिफैक्ट पाथ मौजूद है और आउटपुट ओवरफ्लो होता है (या फ़ाइल पहले से सक्रिय है), तो पूरी स्ट्रीम को आर्टिफैक्ट फ़ाइल में लिखता है,
• जब मेमोरी थ्रेशोल्ड ओवरफ्लो होता है, इन-मेमोरी बफ़र को टेल तक ट्रिम करता है (UTF-8 बाउंड्री सेफ),
• ओवरफ्लो/फ़ाइल स्पिल होने पर truncated मार्क करता है।

dump() रिटर्न करता है:

• output (संभवतः एनोटेटेड प्रीफ़िक्स),
• truncated,
• totalLines/totalBytes,
• outputLines/outputBytes,
• artifactId यदि आर्टिफैक्ट फ़ाइल सक्रिय थी।

लॉन्ग-आउटपुट चेतावनी

OutputSink में रनटाइम ट्रंकेशन बाइट-थ्रेशोल्ड आधारित है (50KB डिफ़ॉल्ट)। यह इस कोड पाथ में एक हार्ड 2000-लाइन कैप लागू नहीं करता।

लाइव टूल अपडेट

नॉन-PTY निष्पादन के लिए, BashTool पार्शियल अपडेट के लिए एक अलग TailBuffer का उपयोग करता है और कमांड चलते समय onUpdate स्नैपशॉट एमिट करता है।

PTY निष्पादन के लिए, लाइव रेंडरिंग कस्टम UI ओवरले द्वारा हैंडल की जाती है, न कि onUpdate टेक्स्ट चंक द्वारा।

रिज़ल्ट शेपिंग, मेटाडेटा और एरर मैपिंग

निष्पादन के बाद:

1. cancelled हैंडलिंग:
   • यदि अबॉर्ट सिग्नल अबॉर्टेड है -> ToolAbortError थ्रो करें (अबॉर्ट सेमेंटिक्स),
   • अन्यथा -> ToolError थ्रो करें (टूल विफलता के रूप में माना जाता है)।
2. PTY timedOut -> ToolError थ्रो करें।
3. अंतिम आउटपुट टेक्स्ट पर head/tail फ़िल्टर लागू करें (applyHeadTail, head फिर tail)।
4. खाली आउटपुट (no output) बन जाता है।
5. toolResult(...).truncationFromSummary(result, { direction: "tail" }) के माध्यम से ट्रंकेशन मेटाडेटा अटैच करें।
6. exit-code मैपिंग:
   • गायब exit code -> ToolError("... missing exit status")
   • नॉन-ज़ीरो exit -> ToolError("... Command exited with code N")
   • ज़ीरो exit -> सफलता रिज़ल्ट।

सफलता पेलोड संरचना:

• content: टेक्स्ट आउटपुट,
• details.meta.truncation जब ट्रंकेटेड हो, जिसमें शामिल हैं:
  • direction, truncatedBy, कुल/आउटपुट लाइन+बाइट काउंट,
  • shownRange,
  • artifactId जब उपलब्ध हो।

क्योंकि बिल्ट-इन टूल wrapToolWithMetaNotice() से रैप होते हैं, ट्रंकेशन नोटिस टेक्स्ट स्वचालित रूप से अंतिम टेक्स्ट कंटेंट में जोड़ा जाता है (उदाहरण के लिए: Full: artifact://<id>)।

रेंडरिंग पाथ

टूल-कॉल रेंडरर (bashToolRenderer)

bashToolRenderer टूल-कॉल मैसेज (toolCall / toolResult) के लिए उपयोग किया जाता है:

• कोलैप्स्ड मोड विज़ुअल-लाइन-ट्रंकेटेड प्रीव्यू दिखाता है,
• एक्सपैंडेड मोड वर्तमान में उपलब्ध सभी आउटपुट टेक्स्ट दिखाता है,
• वार्निंग लाइन ट्रंकेशन कारण और ट्रंकेटेड होने पर artifact://<id> शामिल करती है,
• टाइमआउट मान (आर्ग्स से) फुटर मेटाडेटा लाइन में दिखाया जाता है।

चेतावनी: पूर्ण आर्टिफैक्ट एक्सपैंशन

BashRenderContext में isFullOutput है, लेकिन वर्तमान रेंडरर कॉन्टेक्स्ट बिल्डर bash टूल रिज़ल्ट के लिए इसे सेट नहीं करता। एक्सपैंडेड व्यू अभी भी रिज़ल्ट कंटेंट (tail/ट्रंकेटेड आउटपुट) में पहले से मौजूद टेक्स्ट का उपयोग करता है जब तक कि कोई अन्य कॉलर पूर्ण आर्टिफैक्ट कंटेंट प्रदान न करे।

यूज़र बैंग-कमांड घटक (BashExecutionComponent)

BashExecutionComponent इंटरेक्टिव मोड में यूज़र ! कमांड के लिए है (मॉडल टूल कॉल नहीं):

• चंक को लाइव स्ट्रीम करता है,
• कोलैप्स्ड प्रीव्यू अंतिम 20 लॉजिकल लाइनें रखता है,
• प्रति लाइन 4000 कैरेक्टर पर लाइन क्लैंप,
• मेटाडेटा मौजूद होने पर ट्रंकेशन + आर्टिफैक्ट वार्निंग दिखाता है,
• कैंसल/एरर/exit स्टेट को अलग-अलग मार्क करता है।

यह घटक CommandController.handleBashCommand() द्वारा वायर्ड है और AgentSession.executeBash() से फीड होता है।

मोड-विशिष्ट व्यवहार अंतर

सर्फेस	एंट्री पाथ	PTY योग्य	लाइव आउटपुट UX	एरर सर्फेसिंग
इंटरेक्टिव टूल कॉल	BashTool.execute	हाँ, जब bash.virtualTerminal=on और UI मौजूद हो और PI_NO_PTY!=1	PTY ओवरले (इंटरेक्टिव) या स्ट्रीम्ड टेल अपडेट	टूल एरर toolResult.isError बन जाते हैं
प्रिंट मोड टूल कॉल	BashTool.execute	नहीं (कोई UI संदर्भ नहीं)	कोई TUI ओवरले नहीं; आउटपुट इवेंट स्ट्रीम/अंतिम असिस्टेंट टेक्स्ट फ्लो में दिखता है	समान टूल एरर मैपिंग
RPC टूल कॉल (एजेंट टूलिंग)	BashTool.execute	आमतौर पर कोई UI नहीं -> नॉन-PTY	स्ट्रक्चर्ड टूल इवेंट/रिज़ल्ट	समान टूल एरर मैपिंग
इंटरेक्टिव बैंग कमांड (!)	AgentSession.executeBash + BashExecutionComponent	नहीं (executor सीधे उपयोग करता है)	समर्पित bash निष्पादन घटक	Controller एक्सेप्शन कैच करता है और UI एरर दिखाता है
RPC bash कमांड	rpc-mode -> session.executeBash	नहीं	BashResult सीधे रिटर्न करता है	Consumer रिटर्न किए गए फ़ील्ड हैंडल करता है

ऑपरेशनल चेतावनियाँ

• Interceptor केवल तभी कमांड ब्लॉक करता है जब सुझाया गया टूल वर्तमान में संदर्भ में उपलब्ध हो।
• यदि आर्टिफैक्ट आवंटन विफल होता है, ट्रंकेशन अभी भी होता है लेकिन कोई artifact:// बैक-रेफ़रेंस उपलब्ध नहीं होता।
• शेल सेशन कैश में इस मॉड्यूल में कोई स्पष्ट इवेक्शन नहीं है; लाइफटाइम प्रोसेस-स्कोप्ड है।
• PTY और नॉन-PTY टाइमआउट सर्फेस अलग हैं:
  • PTY स्पष्ट timedOut रिज़ल्ट फ़ील्ड एक्सपोज़ करता है,
  • नॉन-PTY टाइमआउट को cancelled + annotation सारांश में मैप करता है।

कार्यान्वयन फ़ाइलें

• src/tools/bash.ts — टूल एंट्रीपॉइंट, नॉर्मलाइज़ेशन/इंटरसेप्शन, PTY/नॉन-PTY चयन, रिज़ल्ट/एरर मैपिंग, bash टूल रेंडरर।
• src/tools/bash-normalize.ts — कमांड नॉर्मलाइज़ेशन और पोस्ट-रन head/tail फ़िल्टरिंग।
• src/tools/bash-interceptor.ts — interceptor नियम मिलान और ब्लॉक्ड-कमांड मैसेज।
• src/exec/bash-executor.ts — नॉन-PTY executor, शेल सेशन पुनः उपयोग, कैंसलेशन वायरिंग, आउटपुट sink इंटीग्रेशन।
• src/tools/bash-interactive.ts — PTY रनटाइम, ओवरले UI, इनपुट नॉर्मलाइज़ेशन, नॉन-इंटरेक्टिव env डिफ़ॉल्ट।
• src/session/streaming-output.ts — OutputSink ट्रंकेशन/आर्टिफैक्ट स्पिल और सारांश मेटाडेटा।
• src/tools/output-utils.ts — आर्टिफैक्ट आवंटन हेल्पर और स्ट्रीमिंग टेल बफ़र।
• src/tools/output-meta.ts — ट्रंकेशन मेटाडेटा शेप + नोटिस इंजेक्शन रैपर।
• src/session/agent-session.ts — सेशन-लेवल executeBash, मैसेज रिकॉर्डिंग, अबॉर्ट लाइफसाइकल।
• src/modes/components/bash-execution.ts — इंटरेक्टिव ! कमांड निष्पादन घटक।
• src/modes/controllers/command-controller.ts — इंटरेक्टिव ! कमांड UI स्ट्रीम/अपडेट कम्पलीशन के लिए वायरिंग।
• src/modes/rpc/rpc-mode.ts — RPC bash और abort_bash कमांड सर्फेस।
• src/internal-urls/artifact-protocol.ts — artifact://<id> रिज़ॉल्यूशन।