संक्षेपण और शाखा सारांश

संक्षेपण और शाखा सारांश दो ऐसे तंत्र हैं जो लंबे सत्रों को पूर्व कार्य संदर्भ खोए बिना उपयोग योग्य बनाए रखते हैं।

• संक्षेपण वर्तमान शाखा पर पुराने इतिहास को एक सारांश में पुनर्लेखित करता है।
• शाखा सारांश /tree नेविगेशन के दौरान परित्यक्त शाखा संदर्भ को कैप्चर करता है।

दोनों को सत्र प्रविष्टियों के रूप में संरक्षित किया जाता है और LLM इनपुट पुनर्निर्माण के दौरान उपयोगकर्ता-संदर्भ संदेशों में वापस परिवर्तित किया जाता है।

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

• src/session/compaction/compaction.ts
• src/session/compaction/branch-summarization.ts
• src/session/compaction/pruning.ts
• src/session/compaction/utils.ts
• src/session/session-manager.ts
• src/session/agent-session.ts
• src/session/messages.ts
• src/extensibility/hooks/types.ts
• src/config/settings-schema.ts

सत्र प्रविष्टि मॉडल

संक्षेपण और शाखा सारांश प्रथम-श्रेणी की सत्र प्रविष्टियाँ हैं, न कि सामान्य असिस्टेंट/उपयोगकर्ता संदेश।

• CompactionEntry
  • type: "compaction"
  • summary, वैकल्पिक shortSummary
  • firstKeptEntryId (संक्षेपण सीमा)
  • tokensBefore
  • वैकल्पिक details, preserveData, fromExtension
• BranchSummaryEntry
  • type: "branch_summary"
  • fromId, summary
  • वैकल्पिक details, fromExtension

जब संदर्भ पुनर्निर्मित होता है (buildSessionContext):

1. सक्रिय पथ पर नवीनतम संक्षेपण एक compactionSummary संदेश में परिवर्तित होता है।
2. firstKeptEntryId से संक्षेपण बिंदु तक की रखी गई प्रविष्टियाँ पुनः शामिल की जाती हैं।
3. पथ पर बाद की प्रविष्टियाँ जोड़ी जाती हैं।
4. branch_summary प्रविष्टियाँ branchSummary संदेशों में परिवर्तित होती हैं।
5. custom_message प्रविष्टियाँ custom संदेशों में परिवर्तित होती हैं।

वे कस्टम रोल्स तब convertToLlm() में स्थैतिक टेम्पलेट्स का उपयोग करके LLM-सामना करने वाले उपयोगकर्ता संदेशों में रूपांतरित होते हैं:

• prompts/compaction/compaction-summary-context.md
• prompts/compaction/branch-summary-context.md

संक्षेपण पाइपलाइन

ट्रिगर

संक्षेपण तीन तरीकों से चल सकता है:

1. मैन्युअल: /compact [instructions] AgentSession.compact(...) को कॉल करता है।
2. स्वचालित ओवरफ़्लो रिकवरी: एक असिस्टेंट त्रुटि के बाद जो संदर्भ ओवरफ़्लो से मेल खाती है।
3. स्वचालित थ्रेशोल्ड संक्षेपण: एक सफल टर्न के बाद जब संदर्भ थ्रेशोल्ड से अधिक हो जाता है।

संक्षेपण आकार (दृश्य)

Before compaction:

  entry:  0     1     2     3      4     5     6      7      8     9
        ┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬──────┐
        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool │
        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴──────┘
                └────────┬───────┘ └──────────────┬──────────────┘
               messagesToSummarize            kept messages
                                   ↑
                          firstKeptEntryId (entry 4)

After compaction (new entry appended):

  entry:  0     1     2     3      4     5     6      7      8     9      10
        ┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬──────┬─────┐
        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool │ cmp │
        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴──────┴─────┘
               └──────────┬──────┘ └──────────────────────┬───────────────────┘
                 not sent to LLM                    sent to LLM
                                                         ↑
                                              starts from firstKeptEntryId

What the LLM sees:

  ┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
  │ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
  └────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
       ↑         ↑      └─────────────────┬────────────────┘
    prompt   from cmp          messages from firstKeptEntryId

ओवरफ़्लो-रिट्री बनाम थ्रेशोल्ड संक्षेपण

दोनों स्वचालित पथ जानबूझकर अलग हैं:

• ओवरफ़्लो-रिट्री संक्षेपण

  • ट्रिगर: वर्तमान-मॉडल असिस्टेंट त्रुटि संदर्भ ओवरफ़्लो के रूप में पहचानी जाती है।
  • विफल असिस्टेंट त्रुटि संदेश रिट्री से पहले सक्रिय एजेंट स्थिति से हटा दिया जाता है।
  • ऑटो संक्षेपण reason: "overflow" और willRetry: true के साथ चलता है।
  • सफलता पर, एजेंट संक्षेपण के बाद स्वतः जारी रहता है (agent.continue())।

• थ्रेशोल्ड संक्षेपण

  • ट्रिगर: contextTokens > contextWindow - compaction.reserveTokens।
  • reason: "threshold" और willRetry: false के साथ चलता है।
  • सफलता पर, यदि compaction.autoContinue !== false, एक सिंथेटिक प्रॉम्प्ट इंजेक्ट करता है:
    • "Continue if you have next steps."

पूर्व-संक्षेपण प्रूनिंग

संक्षेपण जाँच से पहले, टूल-रिज़ल्ट प्रूनिंग चल सकती है (pruneToolOutputs)।

डिफ़ॉल्ट प्रून नीति:

• नवीनतम 40_000 टूल-आउटपुट टोकन सुरक्षित रखें।
• कम से कम 20_000 कुल अनुमानित बचत की आवश्यकता।
• skill या read से टूल परिणाम कभी न प्रून करें।

प्रून किए गए टूल परिणाम इससे प्रतिस्थापित होते हैं:

• [Output truncated - N tokens]

यदि प्रूनिंग प्रविष्टियों को बदलती है, तो संक्षेपण निर्णयों से पहले सत्र स्टोरेज पुनर्लिखित होता है और एजेंट संदेश स्थिति ताज़ा होती है।

सीमा और कट-पॉइंट लॉजिक

prepareCompaction() केवल अंतिम संक्षेपण प्रविष्टि (यदि कोई हो) के बाद से प्रविष्टियों पर विचार करता है।

1. पिछला संक्षेपण इंडेक्स खोजें।
2. boundaryStart = prevCompactionIndex + 1 की गणना करें।
3. उपलब्ध उपयोग अनुपात का उपयोग करके keepRecentTokens को अनुकूलित करें।
4. सीमा विंडो पर findCutPoint() चलाएँ।

मान्य कट पॉइंट में शामिल हैं:

• रोल्स वाले संदेश प्रविष्टियाँ: user, assistant, bashExecution, hookMessage, branchSummary, compactionSummary
• custom_message प्रविष्टियाँ
• branch_summary प्रविष्टियाँ

कठोर नियम: कभी भी toolResult पर न काटें।

यदि कट पॉइंट से तुरंत पहले गैर-संदेश मेटाडेटा प्रविष्टियाँ हैं (model_change, thinking_level_change, लेबल आदि), तो उन्हें कट इंडेक्स को पीछे ले जाकर रखे गए क्षेत्र में खींचा जाता है जब तक कि कोई संदेश या संक्षेपण सीमा नहीं मिलती।

स्प्लिट-टर्न हैंडलिंग

यदि कट पॉइंट यूज़र-टर्न स्टार्ट पर नहीं है, तो संक्षेपण इसे स्प्लिट टर्न के रूप में मानता है।

टर्न स्टार्ट पहचान इन्हें यूज़र-टर्न सीमाओं के रूप में मानती है:

• message.role === "user"
• message.role === "bashExecution"
• custom_message प्रविष्टि
• branch_summary प्रविष्टि

स्प्लिट-टर्न संक्षेपण दो सारांश उत्पन्न करता है:

1. इतिहास सारांश (messagesToSummarize)
2. टर्न-प्रीफ़िक्स सारांश (turnPrefixMessages)

अंतिम संग्रहीत सारांश इस प्रकार मर्ज किया जाता है:

<history summary>

---

**Turn Context (split turn):**

<turn prefix summary>

सारांश निर्माण

compact(...) क्रमबद्ध वार्तालाप पाठ से सारांश बनाता है:

1. convertToLlm() के माध्यम से संदेश परिवर्तित करें।
2. serializeConversation() के साथ क्रमबद्ध करें।
3. <conversation>...</conversation> में लपेटें।
4. वैकल्पिक रूप से <previous-summary>...</previous-summary> शामिल करें।
5. वैकल्पिक रूप से हुक संदर्भ को <additional-context> सूची के रूप में इंजेक्ट करें।
6. SUMMARIZATION_SYSTEM_PROMPT के साथ सारांशीकरण प्रॉम्प्ट निष्पादित करें।

प्रॉम्प्ट चयन:

• पहला संक्षेपण: compaction-summary.md
• पूर्व सारांश के साथ पुनरावृत्त संक्षेपण: compaction-update-summary.md
• स्प्लिट-टर्न दूसरा पास: compaction-turn-prefix.md
• संक्षिप्त UI सारांश: compaction-short-summary.md

रिमोट सारांशीकरण मोड:

• यदि compaction.remoteEndpoint सेट है, तो संक्षेपण POST करता है:
  • { systemPrompt, prompt }
• कम से कम { summary } युक्त JSON की अपेक्षा करता है।

सारांशों में फ़ाइल-ऑपरेशन संदर्भ

संक्षेपण असिस्टेंट टूल कॉल का उपयोग करके संचयी फ़ाइल गतिविधि ट्रैक करता है:

• read(path) → रीड सेट
• write(path) → संशोधित सेट
• edit(path) → संशोधित सेट

संचयी व्यवहार:

• पूर्व संक्षेपण विवरण केवल तब शामिल करता है जब पूर्व प्रविष्टि pi-जनरेटेड हो (fromExtension !== true)।
• स्प्लिट टर्न में, टर्न-प्रीफ़िक्स फ़ाइल ऑपरेशन भी शामिल होते हैं।
• readFiles में संशोधित फ़ाइलें शामिल नहीं होतीं।

सारांश पाठ में प्रॉम्प्ट टेम्पलेट के माध्यम से फ़ाइल टैग जोड़े जाते हैं:

<read-files>
...
</read-files>
<modified-files>
...
</modified-files>

संरक्षित करना और पुनः लोड करना

सारांश निर्माण (या हुक-प्रदत्त सारांश) के बाद, एजेंट सत्र:

1. appendCompaction(...) के साथ CompactionEntry जोड़ता है।
2. buildSessionContext() के माध्यम से संदर्भ पुनर्निर्मित करता है।
3. लाइव एजेंट संदेशों को पुनर्निर्मित संदर्भ से प्रतिस्थापित करता है।
4. session_compact हुक इवेंट उत्सर्जित करता है।

शाखा सारांशीकरण पाइपलाइन

शाखा सारांशीकरण ट्री नेविगेशन से जुड़ा है, टोकन ओवरफ़्लो से नहीं।

ट्रिगर

navigateTree(...) के दौरान:

1. collectEntriesForBranchSummary(...) का उपयोग करके पुराने लीफ से सामान्य पूर्वज तक परित्यक्त प्रविष्टियाँ गणना करें।
2. यदि कॉलर ने सारांश अनुरोध किया (options.summarize), लीफ स्विच करने से पहले सारांश उत्पन्न करें।
3. यदि सारांश मौजूद है, branchWithSummary(...) का उपयोग करके इसे नेविगेशन लक्ष्य पर संलग्न करें।

संचालनात्मक रूप से यह आमतौर पर /tree प्रवाह द्वारा संचालित होता है जब branchSummary.enabled सक्षम हो।

शाखा स्विच आकार (दृश्य)

Tree before navigation:

         ┌─ B ─ C ─ D (old leaf, being abandoned)
    A ───┤
         └─ E ─ F (target)

Common ancestor: A
Entries to summarize: B, C, D

After navigation with summary:

         ┌─ B ─ C ─ D ─ [summary of B,C,D]
    A ───┤
         └─ E ─ F (new leaf)

तैयारी और टोकन बजट

generateBranchSummary(...) बजट की गणना इस प्रकार करता है:

• tokenBudget = model.contextWindow - branchSummary.reserveTokens

prepareBranchEntries(...) तब:

1. पहला पास: सभी सारांशित प्रविष्टियों से संचयी फ़ाइल ऑपरेशन एकत्र करें, पूर्व pi-जनरेटेड branch_summary विवरण सहित।
2. दूसरा पास: नवीनतम → पुरानी की ओर चलते हुए टोकन बजट पहुँचने तक संदेश जोड़ें।
3. हालिया संदर्भ संरक्षित करना प्राथमिकता दें।
4. निरंतरता के लिए बजट सीमा के पास बड़ी सारांश प्रविष्टियाँ अभी भी शामिल हो सकती हैं।

संक्षेपण प्रविष्टियाँ शाखा सारांशीकरण इनपुट के दौरान संदेशों (compactionSummary) के रूप में शामिल होती हैं।

सारांश निर्माण और दृढ़ता

शाखा सारांशीकरण:

1. चयनित संदेशों को परिवर्तित और क्रमबद्ध करता है।
2. <conversation> में लपेटता है।
3. आपूर्ति किए गए कस्टम निर्देश उपयोग करता है, अन्यथा branch-summary.md।
4. SUMMARIZATION_SYSTEM_PROMPT के साथ सारांशीकरण मॉडल को कॉल करता है।
5. branch-summary-preamble.md प्रीपेंड करता है।
6. फ़ाइल-ऑपरेशन टैग जोड़ता है।

परिणाम वैकल्पिक विवरण (readFiles, modifiedFiles) के साथ BranchSummaryEntry के रूप में संग्रहीत होता है।

एक्सटेंशन और हुक टचपॉइंट

session_before_compact

पूर्व-संक्षेपण हुक।

कर सकता है:

• संक्षेपण रद्द करना ({ cancel: true })
• पूर्ण कस्टम संक्षेपण पेलोड प्रदान करना ({ compaction: CompactionResult })

session.compacting

डिफ़ॉल्ट संक्षेपण के लिए प्रॉम्प्ट/संदर्भ अनुकूलन हुक।

वापस कर सकता है:

• prompt (बेस सारांश प्रॉम्प्ट ओवरराइड)
• context (<additional-context> में इंजेक्ट की गई अतिरिक्त संदर्भ पंक्तियाँ)
• preserveData (संक्षेपण प्रविष्टि पर संग्रहीत)

session_compact

सहेजी गई compactionEntry और fromExtension फ्लैग के साथ पोस्ट-संक्षेपण अधिसूचना।

session_before_tree

डिफ़ॉल्ट शाखा सारांश निर्माण से पहले ट्री नेविगेशन पर चलता है।

कर सकता है:

• नेविगेशन रद्द करना
• कस्टम { summary: { summary, details } } प्रदान करना जो उपयोगकर्ता द्वारा सारांशीकरण अनुरोध पर उपयोग होता है

session_tree

नए/पुराने लीफ और वैकल्पिक सारांश प्रविष्टि को उजागर करने वाला पोस्ट-नेविगेशन इवेंट।

रनटाइम व्यवहार और विफलता सिमेंटिक्स

• मैन्युअल संक्षेपण पहले वर्तमान एजेंट ऑपरेशन को निरस्त करता है।
• abortCompaction() मैन्युअल और ऑटो-संक्षेपण दोनों कंट्रोलर्स को रद्द करता है।
• ऑटो संक्षेपण UI/स्थिति अपडेट के लिए स्टार्ट/एंड सत्र इवेंट उत्सर्जित करता है।
• ऑटो संक्षेपण कई मॉडल उम्मीदवारों का प्रयास कर सकता है और क्षणिक विफलताओं को पुनः प्रयास कर सकता है।
• ओवरफ़्लो त्रुटियाँ सामान्य रिट्री पथ से बाहर हैं क्योंकि उन्हें संक्षेपण द्वारा संभाला जाता है।
• यदि ऑटो-संक्षेपण विफल होता है:
  • ओवरफ़्लो पथ Context overflow recovery failed: ... उत्सर्जित करता है
  • थ्रेशोल्ड पथ Auto-compaction failed: ... उत्सर्जित करता है
• शाखा सारांशीकरण को अबॉर्ट सिग्नल (जैसे, Escape) के माध्यम से रद्द किया जा सकता है, रद्द/निरस्त नेविगेशन परिणाम लौटाते हुए।

सेटिंग्स और डिफ़ॉल्ट

settings-schema.ts से:

• compaction.enabled = true
• compaction.reserveTokens = 16384
• compaction.keepRecentTokens = 20000
• compaction.autoContinue = true
• compaction.remoteEndpoint = undefined
• branchSummary.enabled = false
• branchSummary.reserveTokens = 16384

ये मान रनटाइम पर AgentSession और संक्षेपण/शाखा सारांशीकरण मॉड्यूल द्वारा उपभोग किए जाते हैं।