cut-at-k ماذا يقول عميلك عن بثّ انقطع قبل نهايته

البثّ الذي ينقطع باكرًا ليس حالة نادرة

يسقط الاتصال. تنفد مهلة الوسيط. يموت المُنتِج في منتصف الجملة، أو يضغط القارئ زرّ الإيقاف. ينتهي البثّ حيث ينتهي، وعلى مكتبة العميل أن تقول لمُستدعيها شيئًا عمّا جرى للتوّ. واختبار هذا المسار يعني اختيار نقطة قطع.

يزيل cut-at-k هذا الاختيار. يأخذ بثًّا واحدًا، ويمرّره عبر عميلك مرّة كاملًا ومرّة عند كل بادئة منه، ثم يسأل عند كل قطع سؤالين:

• هل تغيّر الرأس؟ القطع قد يُفقد الذيل، لكنه يجب ألّا يغيّر أبدًا ما جاء قبل موضع القطع.
• وهل يقول المستهلك ذلك؟ التشغيل المقطوع يجب ألّا يبلّغ بما يبلّغ به التشغيل نفسه حين يكتمل.

السؤال الثاني هو موضع الخلل في العادة، وهو خلل صامت حين يقع: الوعد يُحَلّ، وكائن النتيجة يبدو عاديًا، ولا شيء فيه يقول إن هذا الجواب نصف جواب.

لا تعرف شيئًا عن بروتوكولك

أنت تعطيها الأحداث ودالّة إعادة تشغيل، وهي تعطيك الحلقة والمقارنة. أحداث SSE، أو أُطر WebSocket، أو عيّنة JSON سطرية، أو مصفوفة بنيتها بيدك — لا تنظر داخل أي حدث قط.

npm install cut-at-k

import { severAtEveryPoint } from 'cut-at-k';

await severAtEveryPoint({
  events,                                   // the stream, as an array
  label: 'checkout-run',
  replay: (prefix) => runMyClient(prefix)   // called whole, then per prefix
});

ثلاث نقاط دخول تحمل العمل: severAtEveryPoint تشغّل الإعادات، وsummarise تختصرها إلى تقرير، وformat تطبعه. بدون أي اعتماديات، وعشرة ملفات، ورخصة MIT.

ترفض أن تصرخ «ذئب»

ثلاثة أشياء تبدو متطابقة في الأرقام الخام، وواحد منها فقط هو النتيجة التي تستحقّ الإبلاغ.

• قطعٌ لم يُفقد شيئًا — يقع بعد آخر حدث محتوى وقبل أحداث المسك الختامية. يبلّغ المستهلك بالشيء نفسه لأن لا شيء ناقصًا، وهو محقّ في ذلك.
• بثٌّ غير صالح عن قصد. مجموعات المطابقة مليئة بهذا، والقطع قبل الخطأ المتعمَّد يجعل البثّ الكامل يسلّم أقلّ ممّا تسلّمه البادئة. فتنقلب المقارنة، ولا تعني شيئًا.
• قطعٌ أفقد محتوى ثم أُبلغ عنه كأنه لم يُفقد شيئًا. هذا وحده هو الاكتشاف.

لذلك لا تبلّغ summarise بأي عيب إطلاقًا ما لم تمرّر لها مُسنِدًا باسم lostContent. أنت من يقرّر ما يُعدّ محتوى في بروتوكولك، والأداة لن تخمّن نيابةً عنك. والبثوث المستبعَدة لكونها غير صالحة عن قصد تعود في صورة عدد لا أن تختفي بهدوء، فيبقى في وسعك دائمًا أن ترى كم استُبعد من المجموعة.

وقد تعلّمنا هذا بالخطأ. النسخة الأولى من summarise لم تميّز بين أيّ من هذه الحالات، فعدّت 154 قطعًا مشكلةً في مجموعة كان فيها 54. ويحتفظ README بالجملة التي خرجت من ذلك: «A tool that cries wolf is worse than no tool» — أي أن أداةً تصرخ «ذئب» أسوأ من لا أداة.

تشغيلها على AG-UI: 227 قطعًا، و54 أفقدت شيئًا بصمت

يشحن AG-UI 68 عيّنة مطابقة كتبها مؤلّفو البروتوكول أنفسهم. اثنتان منها بطول حدث واحد فلا نقطة قطع فيهما، فأُعيد تشغيل 66 — كلّ واحدة عبر HttpAgent حقيقي على HTTP وSSE حقيقيَّين مع @ag-ui/client 1.0.0، كاملةً ثم مقطوعةً عند كل حدّ بين حدثين.

48 streams, 227 cuts, 18 streams excluded as invalid on purpose
4 cuts threw during replay

reported the same as the whole run    : 154
  of which something was actually lost : 54
  of those, no terminal event either   : 52
spread across                          : 34 streams

أصغر الحالات أوضحها. خذ العيّنة المسمّاة conformant-run-is-quiet واقطعها بعد حدثها الرابع. الاستدعاء المقطوع والاستدعاء المكتمل كلاهما يُحَلّ، ولا أحد منهما يُرفَض. وRunAgentResult لا يحمل أي حقل يقول أيّهما قُطع. وعدد الرسائل 1 في الحالتين. فالمُستدعي الذي يتحقّق هل نجح التشغيل، أو كم رسالة عادت، يُقال له الشيء نفسه تمامًا من تشغيل اكتمل ومن تشغيل توقّف في منتصف الجملة.

وأربعة من هذه الـ227 قطعًا رمت استثناءً أثناء إعادة التشغيل. وهي تبقى ضمن المجموع وتُنحّى جانبًا قبل المقارنة، لأن قطعًا يُعطِّل العميل اكتشافٌ مختلف عن قطعٍ أبلغ بشيء خاطئ.

ما لا تدّعيه هذه الصفحة

يستطيع المشترك أن يكشف هذا اليوم. فـonRunFinishedEvent يقع على التشغيل المكتمل لا على المقطوع، بينما يقع onRunFinalized على كليهما — فالفرق ملحوظ إن كنت مُنصتًا على تلك القناة. والادّعاء هنا أضيق من ذلك: الاستدعاء المنتظَر لا يُظهره. وتصادف أن تلك هي القناة التي يستعملها أكثر المُستدعين، ولهذا يستحقّ الأمر التدوين، لكنه ليس قولًا بأن المعلومة غير متاحة.

وليس في هذا كلّه اكتشاف. فقد أُبلغ عن السلوك في 3 أغسطس 2026 في ag-ui-protocol/ag-ui#2300، وطلب الدمج PR #2354 مفتوح منذ 7 أغسطس 2026 ويحمل الإصلاح. وكلاهما كان ما يزال مفتوحًا حين كُتبت هذه الصفحة. والحجّة لصالح الأداة ليست الجِدّة بل الاتّساع: وُجد العطل مرّة واحدة، يدويًا، على بثّ واحد، والحلقة تُظهر 54 قطعًا من الشكل نفسه عبر 34 بثًّا دون أن يضطرّ أحد إلى تخمين موضع النظر.

ستّ مكتبات، والسؤال نفسه، وأربعة أجوبة سليمة

يحمل المستودع مسبارات تسأل خمس قواعد شيفرة أخرى: ماذا تقول لمُستدعيها حين يُقطع البثّ؟ أربع منها تجيب إجابة صحيحة:

• يبلّغ Vercel AI SDK بسبب إنهاء قيمته other على تشغيل مقطوع، أو يرفع خطأً إن لم يمرّ أي نصّ إطلاقًا.
• يوقف LangGraph JS نقطة الحفظ عند الموضع الذي توقّف عنده المستهلك المُجهَض، ويقول من أين تُستأنف.
• ذاكرة Mastra ما تزال تحتفظ بما عُرض على المستهلك فعلًا.
• والردّ النهائي في OpenAI Node SDK يحتفظ باستدعاء الأداة الذي بثّه، ولا يدّعي قطّ أنه اكتمل.

أما MCP TypeScript SDK فلم يفعل. فحين يموت شقّ الاستجابة من طلب POST، ينتظر الطلب مهلته كاملة قبل أن يُخبَر المُستدعي — عند كل نقطة قطع، بما فيها نقطة كان نصف الردّ قد وصل عندها.

ستٌّ سُئلت في المجموع، بحساب AG-UI نفسه — وأربع منها سليمة. والمكتبتان اللتان تجيبان إجابة خاطئة، وهما AG-UI وMCP SDK، وجدهما غيرُنا أولًا كلتاهما. هذا هو الحساب الأمين: هذه طريقة لطرح سؤال قديم في كل مكان دفعة واحدة، لا مصدرٌ لاكتشافات جديدة.

أرقام

• الإصدار 0.1.3، نُشر أول مرّة في 25 سبتمبر 2026. رخصة MIT، بدون أي اعتماديات، 10 ملفات، ومنشور مع إثبات مصدر موثّق.
• 21 اختبارًا. 21 ناجحًا و0 فاشلًا — استُنسخت وشُغّلت في 28 سبتمبر 2026.
• 579 تنزيلًا في أيامها الثلاثة الأولى — وهو رقم «الأسبوع الأخير» عند npm. والحزمة عمرها ثلاثة أيام، فهذا هو رقم الشهر أيضًا.
• 0 نجمة على GitHub، وعمرها ثلاثة أيام. اقرأ الاختبارات قبل أن تثق بمخرجاتها.

كيف تستشهد بها

للمكتبة DOI خاصّ بها: 10.5281/zenodo.23002965. ويُشحن ملف CITATION.cff داخل المستودع، فيُملأ منه زرّ Cite this repository في GitHub نفسه.

المشرف

يشرف عليها Redouane — ROSH™ Company Labs. تُرسل الأخطاء وطلبات الميزات إلى مسائل GitHub. وأنفع بلاغ يمكن أن يصل هذا المشروع هو مجموعة عيّنات عدَّ فيها التقريرُ شيئًا اكتشافًا وهو ليس كذلك.