تفعيل الـcompaction على agent
معcreateAgent()، فعّل الـcompaction بخيار compaction. القيمة true تثبّت الـhook بإعداداته الافتراضية: تقليم نتائج الـtools القديمة فوق 90% من window الـmodel. وإذا مررت object فإنك تضبطه بنفسك، وفيه summarizer يختار twoPhaseStrategy() مع الـmodel الذي تعطيه — سلسلة "provider/model" أو LLMProvider. بادئة vendor/ في اسم الـmodel هي التي تحدد الـprovider. مع OpenRouter استخدم openrouter/<vendor>/<model> (مثلاً openrouter/openai/gpt-4o-mini).
strategy وthresholdPercent وcontextWindow وprotectedTokens وreserveOutputTokens وonCompaction (كما في الجدول أدناه) وsummarizer. الجمع بين summarizer وstrategy خطأ في الإعداد — مرّر twoPhaseStrategy({ model }) كقيمة لـstrategy بدلًا منه. createAgent({ hooks }) يقبل أي AgentHook أخرى، وهي تعمل قبل hook الـcompaction، فيرى الـcompaction ما أضافته. الـhooks والـcompaction ينطبقان على send() وstream() والـsessions.
أحداث الـstream
agent.stream() وsession.stream() وAgentExecutor.stream() يبلّغون عن كل عملية compaction بحدثين، داخل الخطوة وقبل استدعاء الـmodel الذي أثارها (انظر Streaming):
كل
compaction.start يتبعه compaction.done واحد بالضبط. إذا لم تستطع الاستراتيجية تصغير شيء، يساوي tokensAfter قيمة tokensBefore وتكون unchanged هي true. بعد ذلك يواصل الـhook الـcompaction على هذا الـtranscript بهدوء: الخطوات اللاحقة التي لا تزال لا تغيّر شيئًا لا تطلق أحداثًا، وأول محاولة تغيّر شيئًا فعلاً تطلق زوج compaction.start / compaction.done الخاص بها كالمعتاد، فلا يبلّغ الـrun العالق فوق العتبة عن زوج أحداث في كل خطوة. وإذا فشلت (أو فشل الـsummarizer فعاد الـhook إلى التقليم)، يُضبط error ويستمر الـrun. الملخص الذي لا يُنزل المحادثة تحت العتبة — أو الذي يكبّرها — مرفوض بالطريقة نفسها: يُضبط error، ويحتفظ الـrun بالنتيجة المقلّمة بدلًا من الملخص، وتكون appliedStrategy هي 'prune-tool-results'. بعد ذلك يكتفي الـhook بتقليم هذا الـtranscript حتى يصبح عدد رسائله ضعف ما كان عليه وقت الرفض، ثم يسمح للـsummarizer بالمحاولة من جديد. فالـsummarizer الذي لا يستطيع المساعدة يكلّف بضعة استدعاءات في الـrun كله، لا استدعاءً في كل خطوة، والـsummarizer الذي رُفض لأنه لم يكن لديه ما يكفي لتلخيصه يحصل على فرصة ثانية. strategy هي الاستراتيجية التي عملت، وهي نفسها على compaction.start وcompaction.done ('prune-tool-results' ما دامت الملخصات متوقفة مؤقتًا). تكون summary هي true عندما تُستبدل الدورات القديمة بملخص (النص نفسه لا يُرسَل؛ استخدم onCompaction، الذي يقبله الـobject أيضًا). send() دون listener لا يطلق أحداثًا. الـhooks تضيف أحداثها بـ ctx.emit?.(...) على سياق preGenerate، وهو موجود عندما يكون للـrun listeners (createAgent({ onEvent }) أو onAgentEvent) أو عندما يعمل بـstream.
الـcompaction على run
createCompactionHook() يعيد AgentHook اسمه compaction. مرّره في createAgent({ hooks }). الإعداد الموصى به: استراتيجية المرحلتين مع model تلخيص رخيص:
estimateTokens (انظر Models, tokens and cost): الرسائل (ومنها الـsystem prompt)، وتعريفات الـtools، و schema المخرجات. وبعد أي استدعاء أبلغ فيه الـprovider عن عدد tokens الـprompt، يضيف الـhook الفرق الذي تجاوز به هذا الرقمُ التقديرَ إلى التقدير التالي في الـrun نفسه، فحتى الـframing المخفي الذي يضيفه الـprovider يُحسب. تعريفات الـtools لا تُضغط، لذا يجب أن تتسع المحادثة لما تتركه هذه التعريفات من العتبة. أعداد الـtokens في compaction.start / compaction.done هي أحجام الطلب هذه. إذا كان الحجم فوق thresholdPercent من الـcontext window، يشغّل الـhook استراتيجيته (وينتظرها إذا كانت async) ويستدعي onCompaction مع أعداد الـtokens، والـtoolCallIds التي قُلّمت، والملخص إن وجد، واسم الاستراتيجية.
الـcompaction لا يُفشل الـrun أبدًا. إذا رمت الاستراتيجية استثناءً، أو فشل استدعاء الـsummarizer، يستمر الـrun (بالمحادثة المقلّمة، أو دون تغيير) وتستلم
onCompaction الـerror.
داخل الـrun، استدعاء الـmodel الخاص بالـsummarizer جزء من الـrun: الـtokens الخاصة به موجودة في result.usage (تحت model الـsummarizer في byModel، وفي modelCalls)، ويأخذ span من نوع chat مع lousho.call.purpose: 'compaction' تحت الـspan الخاص بالـrun، ويُحسب ضمن ميزانيات limits للـrun. (session.compact() وcompactMessages() يعملان خارج أي run، فلا تُحسب استدعاءات التلخيص فيهما في أي مكان.)
يعيد الـhook كتابة transcript الـrun نفسه، لا نسخة منه: مصفوفة messages في الطلب هي قائمة رسائل الـrun، والـhook يغيّرها في مكانها. فتبقى النتيجة المقلّمة أو الملخص في الخطوات اللاحقة، وفي الـcheckpoints (الـsession المستأنفة لا تستعيد السجل الكامل) وفي result.messages، ولا تُضغط مرة أخرى في الخطوة التالية. الـcompaction يُفقد معلومات: إذا احتاج الـmodel نتيجة مقلّمة مرة أخرى، فعليه أن يستدعي الـtool من جديد.
الـmodels المحلية وغير المعروفة
العتبة نسبة من الـcontext window الخاص بالـmodel، فالـcompaction يحتاج الـwindow الحقيقي. لأي model لا يعرفه سجل الـmodels (أغلب الـmodels المحلية)، يفترض الـhook128_000 token ويطبع console.warn مرة واحدة فيه اسم الـmodel. الخادم المحلي يعمل عادةً بـwindow أصغر بكثير، وعندئذٍ لا يعمل الـcompaction أبدًا قبل أن يرفض الخادم الطلب. اضبط الـwindow الذي حمّلت به الـmodel: في LM Studio هو طول السياق المحمّل للـmodel (loaded_context_length من GET /api/v0/models/<id>)، وفي Ollama هو خيار num_ctx (ollama show <model> يطبع القيمة الافتراضية للـmodel).
protectedTokens (40,000) تُحدّ بنصف العتبة، فتبقى أحدث ~3,700 token من window حجمه 8K سليمة، ويمكن تقليم نتائج الـtools الأقدم. اضبط protectedTokens بنفسك إذا أردت حماية أكثر أو أقل؛ واجعلها تحت العتبة.
Tool search يقرأ الـwindow بالطريقة نفسها ويحذّر بالطريقة نفسها؛ والإعداد الخاص به هو toolSearch.contextWindow.
متقدم: executor API
تسجيل الـhook فيHookRegistry للكود الذي يستدعي الـexecutor مباشرة (انظر executor API):
الاستراتيجيات
تقليم نتائج الـtools
pruneToolResultsStrategy() تستبدل بـ content كل نتيجة tool أقدم من الذيل المحمي علامة قصيرة تسمّي الاستدعاء، مثل [pruned: search({"query":"deploy"}) result, 18234 chars; already read] (المعاملات الأطول من 120 حرفًا تُقتطع)، فيعرف الـmodel ما الذي جلبه من قبل، ولا يستدعي الـtool نفسه مرة أخرى لمجرد أن يرى النتيجة. والعلامات بالصيغة القديمة [pruned: search result, 18234 chars] يُتعرَّف عليها وتُترك كما هي. ولا تغيّر أبدًا:
- رسائل system، ولا رسائل user (ومنها الأولى)، ولا دورات assistant — فكل tool call يحتفظ برسالة نتيجته، ويبقى الـtranscript صالحًا لكل provider؛
- نتائج آخر دورة assistant، التي لم يقرأها الـmodel بعد، حتى لو كانت أكبر من
protectedTokens؛ - النتائج المثبتة، ولا النتائج التي هي أصلاً علامة، ولا النتائج الأقصر من العلامة.
تلخيص الدورات القديمة
summarizeStrategy() ترسل الرسائل التي تسبق الذيل المحمي إلى الـsummarizer مع تعليمة مركّزة، وتستبدل بها رسالة user واحدة:
الملخص يُبقي الـtranscript صالحًا لكل provider:
- رسائل system والرسائل المثبتة تبقى في أماكنها، والملخص يحل محل أول رسالة مُلخّصة؛
- دورة assistant تُلخَّص أو تبقى مع كل نتائج الـtools الخاصة بها معًا، فلا يفقد أي tool call نتيجته (ولا تفقد أي نتيجة الـcall الخاص بها)؛
- الرسالة الأخيرة ونتائج آخر دورة assistant تبقى دائمًا.
error.
المرحلتان
twoPhaseStrategy() تأخذ الخيارات نفسها. تقلّم نتائج الـtools أولاً — وهذا مجاني — ولا تستدعي الـsummarizer إلا إذا كانت المحادثة المقلّمة لا تزال فوق thresholdPercent من الـcontext window. عندئذٍ يقرأ الـsummarizer المحادثة المقلّمة. وإذا فشل، تبقى المحادثة المقلّمة ويُبلَّغ عن error.
تثبيت الرسائل
pinMessage(message) تعيد نسخة من الرسالة موسومة بأنها مثبتة (تضبط metadata.pinned: true؛ وMessage.metadata بيانات للتطبيق لا تُرسل إلى الـmodel أبدًا). الاستراتيجيات المدمجة لا تقلّم رسالة مثبتة ولا تلخّصها أبدًا؛ ونتيجة tool مثبتة تحفظ دورة الـassistant التابعة لها كاملة. ثبّت ما يجب أن يراه الـagent كاملًا دائمًا، مثل نص المهمة أو مستند أساسي:
isPinned() أيضًا.
الـcompaction يدويًا
compactMessages(messages, options) تشغّل استراتيجية مرة واحدة، مهما كان حجم المحادثة، وتعيد promise نتيجته مصفوفة جديدة (لا يُعدَّل المدخل). استخدمها لتصغير transcript مخزّن قبل أن تكمله:
الـcompaction على session
session.compact(options?) تعمل compaction لسجل session فورًا، مهما كان حجمه، وتحفظه في الـstore الخاص بالـsession (الذاكرة أو ملف أو SQLite أو KV) وتعيد { messagesBefore, messagesAfter, tokensBefore, tokensAfter, strategy, error? }. تشغّل options.strategy إن وُجدت، وإلا استراتيجية agent.session({ compaction }) — وهي القيمة نفسها التي يأخذها createAgent({ compaction })، وcompaction الخاص بالـagent إذا لم تضبط الـsession واحدة — وإلا تقلّم نتائج الـtools القديمة. الرسائل المثبتة تبقى. والـsession التي لا رسائل فيها تنتهي دون أن تفعل شيئًا. يُرفض الاستدعاء بـ LOUSHO_SESSION_BUSY إذا كانت هناك turn قيد التشغيل، وبـ LOUSHO_SESSION_TURN_PENDING / LOUSHO_SESSION_AWAITING_APPROVAL إذا كانت هناك durable turn لم تنتهِ. الـlisteners التي أُضيفت بـ session.on() تستلم compaction.start وcompaction.done مع trigger: 'manual'. أما session.clear() فتفرّغ الـtranscript، وتحذف الـcheckpoint الخاص بكل turn وسجل الـcheckpoints، وتطلق context.cleared.
كتابة strategy
الاستراتيجية اسم ودالةcompact()، ويمكن أن تكون async. تستلم الرسائل، وعدّاد tokens لـmodel الطلب، والـcontext window، وprotectedTokens، وthresholdTokens (الحجم الذي يجب أن تنزل تحته)، وsignal الإلغاء الخاصة بالـrun، وتعيد الرسائل الجديدة مع عدد الـtokens قبل وبعد (واختياريًا summary أو error). أعِد مصفوفة الإدخال دون تغيير عندما لا يكون هناك ما تفعله: عندئذٍ يترك الـhook الـrun على حاله ولا يستدعي onCompaction.
compaction.start وcompaction.done مثل الاستراتيجيات المدمجة. وonCompaction (على createCompactionHook()) تظل تستلم نص الملخص وكائن Error.