गैर-कॉम्पैक्शन ऑटो-रिट्राई नीति

यह दस्तावेज़ AgentSession में मानक API-त्रुटि रिट्राई पथ का वर्णन करता है।

यह स्पष्ट रूप से ऑटो-कॉम्पैक्शन के माध्यम से कॉन्टेक्स्ट-ओवरफ्लो पुनर्प्राप्ति को बाहर करता है। ओवरफ्लो को कॉम्पैक्शन लॉजिक द्वारा संभाला जाता है और इसे अलग से compaction.md में दस्तावेज़ीकृत किया गया है।

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

• ../src/session/agent-session.ts
• ../src/config/settings-schema.ts
• ../src/modes/controllers/event-controller.ts
• ../src/modes/rpc/rpc-mode.ts
• ../src/modes/rpc/rpc-client.ts
• ../src/modes/rpc/rpc-types.ts

कॉम्पैक्शन के साथ दायरे की सीमा

रिट्राई और कॉम्पैक्शन दोनों को एक ही agent_end पथ से जाँचा जाता है, लेकिन इन्हें जानबूझकर अलग रखा गया है:

1. agent_end अंतिम असिस्टेंट संदेश का निरीक्षण करता है।
2. #isRetryableError(...) पहले चलता है।
3. यदि रिट्राई शुरू किया जाता है, तो उस टर्न के लिए कॉम्पैक्शन जाँच छोड़ दी जाती है।
4. कॉन्टेक्स्ट-ओवरफ्लो त्रुटियाँ रिट्राई वर्गीकरण से पूरी तरह बाहर हैं (isContextOverflow(...) रिट्राई को शॉर्ट-सर्किट करता है)।
5. ओवरफ्लो इसलिए मानक रिट्राई के बजाय #checkCompaction(...) तक पहुँचता है।

अर्थात्: ओवरलोड/रेट/सर्वर/नेटवर्क-शैली की विफलताएँ इस रिट्राई नीति का उपयोग करती हैं; कॉन्टेक्स्ट-विंडो ओवरफ्लो कॉम्पैक्शन पुनर्प्राप्ति का उपयोग करता है।

रिट्राई वर्गीकरण

#isRetryableError(...) के लिए निम्नलिखित सभी शर्तें आवश्यक हैं:

• असिस्टेंट का stopReason === "error"
• errorMessage मौजूद हो
• संदेश कॉन्टेक्स्ट ओवरफ्लो नहीं होना चाहिए
• errorMessage #isRetryableErrorMessage(...) से मेल खाता हो

वर्तमान रिट्राई-योग्य पैटर्न सेट (regex-आधारित):

• overloaded
• rate limit / usage limit / too many requests
• HTTP-जैसे सर्वर वर्ग: 429, 500, 502, 503, 504
• service unavailable / server error / internal error
• connection error / fetch failed
• retry delay शब्दावली

यह स्ट्रिंग-पैटर्न वर्गीकरण है, न कि टाइप किए गए प्रोवाइडर त्रुटि कोड।

रिट्राई जीवनचक्र और स्थिति परिवर्तन

रिट्राई द्वारा उपयोग की जाने वाली सेशन स्थिति:

• #retryAttempt: number (0 का अर्थ है निष्क्रिय)
• #retryPromise: Promise<void> | undefined (इन-प्रोग्रेस रिट्राई जीवनचक्र को ट्रैक करता है)
• #retryResolve: (() => void) | undefined (#retryPromise को रिज़ॉल्व करता है)
• #retryAbortController: AbortController | undefined (बैकऑफ़ स्लीप को रद्द करता है)

प्रवाह (#handleRetryableError):

1. retry सेटिंग्स समूह पढ़ें।
2. यदि retry.enabled === false, तुरंत रुकें (false, कोई रिट्राई शुरू नहीं)।
3. #retryAttempt बढ़ाएँ।
4. एक बार #retryPromise बनाएँ (एक चेन में पहला प्रयास)।
5. यदि प्रयास retry.maxRetries से अधिक हो गया, अंतिम विफलता इवेंट भेजें और रुकें।
6. देरी की गणना करें: retry.baseDelayMs * 2^(attempt-1)।
7. usage-limit त्रुटियों के लिए, रिट्राई हिंट्स पार्स करें और auth storage (markUsageLimitReached(...)) को कॉल करें; यदि प्रोवाइडर/मॉडल स्विच सफल होता है, तो देरी को 0 पर सेट करें।
8. auto_retry_start भेजें।
9. एजेंट रनटाइम स्थिति से पिछला असिस्टेंट त्रुटि संदेश हटाएँ (persisted सेशन इतिहास में रखा जाता है)।
10. abort सपोर्ट के साथ स्लीप करें।
11. जागने पर, setTimeout(..., 0) के माध्यम से agent.continue() शेड्यूल करें।

रिट्राई काउंटर क्या रीसेट करता है

#retryAttempt इन मामलों में 0 पर रीसेट होता है:

• रिट्राई शुरू होने के बाद पहला सफल गैर-त्रुटि, गैर-अबोर्टेड असिस्टेंट संदेश (auto_retry_end { success: true } भेजता है)
• बैकऑफ़ स्लीप के दौरान रिट्राई रद्द करना
• अधिकतम रिट्राई अधिक होने का पथ

#retryPromise रिट्राई चेन समाप्त होने पर (सफलता, रद्दीकरण, या अधिकतम-अधिक) #resolveRetry() के माध्यम से रिज़ॉल्व/क्लियर होता है।

बैकऑफ़ और अधिकतम-प्रयास अर्थशास्त्र

सेटिंग्स:

• retry.enabled (डिफ़ॉल्ट true)
• retry.maxRetries (डिफ़ॉल्ट 3)
• retry.baseDelayMs (डिफ़ॉल्ट 2000)

प्रयास क्रमांकन:

• अधिकतम-जाँच से पहले प्रयास काउंटर बढ़ाया जाता है
• प्रारंभ इवेंट वर्तमान प्रयास (1-आधारित) का उपयोग करते हैं
• अधिकतम-अधिक अंत इवेंट attempt: this.#retryAttempt - 1 रिपोर्ट करता है (अंतिम प्रयास किया गया रिट्राई काउंट)

डिफ़ॉल्ट सेटिंग्स के साथ बैकऑफ़ अनुक्रम:

• प्रयास 1: 2000 ms
• प्रयास 2: 4000 ms
• प्रयास 3: 8000 ms

देरी ओवरराइड इनपुट केवल usage-limit हैंडलिंग पथ में उपयोग किए जाते हैं, और केवल auth-storage मॉडल/अकाउंट स्विचिंग निर्णय को प्रभावित करने के लिए। मुख्य गैर-कॉम्पैक्शन रिट्राई पथ में, बैकऑफ़ स्थानीय एक्सपोनेंशियल देरी रहती है जब तक स्विचिंग सफल न हो (delayMs = 0)।

अबोर्ट मैकेनिक्स

स्पष्ट रिट्राई अबोर्ट

abortRetry():

• #retryAbortController को अबोर्ट करता है (यदि मौजूद हो)
• रिट्राई प्रॉमिस को रिज़ॉल्व करता है (#resolveRetry()) ताकि अवेटर्स अनब्लॉक हों

यदि स्लीप के दौरान अबोर्ट होता है, तो catch पथ भेजता है:

• auto_retry_end { success: false, finalError: "Retry cancelled" }
• प्रयास/कंट्रोलर रीसेट करता है

वैश्विक ऑपरेशन अबोर्ट इंटरैक्शन

abort() सक्रिय एजेंट स्ट्रीम को अबोर्ट करने से पहले abortRetry() को कॉल करता है। यह सुनिश्चित करता है कि जब उपयोगकर्ता सामान्य अबोर्ट जारी करता है तो रिट्राई बैकऑफ़ रद्द हो जाता है।

TUI इंटरैक्शन

auto_retry_start पर, EventController:

• Esc हैंडलर को session.abortRetry() में बदलता है
• लोडर टेक्स्ट रेंडर करता है: Retrying (attempt/maxAttempts) in Ns… (esc to cancel)

auto_retry_end पर, यह पूर्व Esc हैंडलर पुनर्स्थापित करता है और लोडर स्थिति साफ़ करता है।

स्ट्रीमिंग और प्रॉम्प्ट पूर्णता व्यवहार

prompt() अंततः agent.prompt(...) वापस आने के बाद #waitForRetry() पर प्रतीक्षा करता है।

प्रभाव:

• एक प्रॉम्प्ट कॉल तब तक पूरी तरह से रिज़ॉल्व नहीं होती जब तक कोई भी शुरू की गई रिट्राई चेन समाप्त न हो (सफलता/विफलता/रद्दीकरण)
• रिट्राई जीवनचक्र एक तार्किक प्रॉम्प्ट निष्पादन सीमा का हिस्सा है

यह कॉलर्स को रिट्राई हो रहे टर्न को बहुत जल्दी पूर्ण मानने से रोकता है।

नियंत्रण: सेटिंग्स और RPC

कॉन्फ़िगरेशन नॉब्स

retry समूह के तहत सेटिंग्स स्कीमा में परिभाषित:

• retry.enabled
• retry.maxRetries
• retry.baseDelayMs

सेशन में प्रोग्रामेटिक टॉगल:

• setAutoRetryEnabled(enabled) retry.enabled लिखता है
• autoRetryEnabled retry.enabled पढ़ता है
• isRetrying रिपोर्ट करता है कि रिट्राई जीवनचक्र प्रॉमिस सक्रिय है या नहीं

RPC नियंत्रण

RPC कमांड सर्फेस:

• set_auto_retry → session.setAutoRetryEnabled(command.enabled)
• abort_retry → session.abortRetry()

क्लाइंट हेल्पर:

• RpcClient.setAutoRetry(enabled)
• RpcClient.abortRetry()

दोनों कमांड सफलता प्रतिक्रियाएँ लौटाते हैं; रिट्राई प्रगति/विफलता विवरण स्ट्रीम किए गए सेशन इवेंट से आते हैं, कमांड प्रतिक्रिया पेलोड से नहीं।

इवेंट उत्सर्जन और विफलता सर्फेसिंग

सेशन-स्तरीय रिट्राई इवेंट:

• auto_retry_start { attempt, maxAttempts, delayMs, errorMessage }
• auto_retry_end { success, attempt, finalError? }

प्रचार:

• AgentSession.subscribe(...) के माध्यम से भेजे गए
• एक्सटेंशन रनर को एक्सटेंशन इवेंट के रूप में अग्रेषित
• RPC मोड में, सीधे JSON इवेंट ऑब्जेक्ट के रूप में अग्रेषित (session.subscribe(event => output(event)))
• TUI में, लोडर/त्रुटि UI के लिए EventController द्वारा उपयोग

अंतिम विफलता सर्फेसिंग:

• अधिकतम-अधिक या रद्दीकरण पर, auto_retry_end.success === false
• TUI दिखाता है: Retry failed after N attempts: <finalError>
• एक्सटेंशन/हुक उन्हीं फ़ील्ड के साथ auto_retry_end प्राप्त करते हैं
• RPC उपभोक्ता stdout स्ट्रीम पर वही इवेंट ऑब्जेक्ट प्राप्त करते हैं

स्थायी रोक की शर्तें

रिट्राई रुक जाता है और इनमें से कोई भी होने पर स्वतः जारी नहीं रहेगा:

• retry.enabled false है
• त्रुटि रिट्राई-वर्गीकृत नहीं है
• त्रुटि कॉन्टेक्स्ट ओवरफ्लो है (कॉम्पैक्शन पथ को सौंपी गई)
• अधिकतम रिट्राई अधिक हो गया
• उपयोगकर्ता रिट्राई रद्द करता है (abort_retry या रिट्राई लोडर के दौरान Esc)
• वैश्विक अबोर्ट (abort) पहले रिट्राई रद्द करता है

काउंटर रीसेट होने के बाद भविष्य की रिट्राई-योग्य त्रुटि पर एक नई रिट्राई चेन अभी भी शुरू हो सकती है।

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

• वर्गीकरण regex टेक्स्ट मिलान है; प्रोवाइडर-विशिष्ट संरचित त्रुटियाँ यहाँ उपयोग नहीं की जाती हैं।
• रिट्राई रनटाइम कॉन्टेक्स्ट से विफल असिस्टेंट त्रुटि को re-continue से पहले हटा देता है, लेकिन सेशन इतिहास में वह त्रुटि प्रविष्टि बनी रहती है।
• RpcSessionState वर्तमान में autoCompactionEnabled को उजागर करता है लेकिन autoRetryEnabled फ़ील्ड नहीं; RPC कॉलर को अपनी टॉगल स्थिति स्वयं ट्रैक करनी होगी या अन्य API के माध्यम से सेटिंग्स क्वेरी करनी होगी।